chore(js-sdk,types): add tsdocs for admin JS SDK methods [6/n] (#10028)

* chore(js-sdk,types): add tsdocs for admin JS SDK methods [6/n]

* fix error

* remove type changes

packages/core/js-sdk/src/admin/product-tag.ts

@@ -14,6 +14,24 @@ export class ProductTag {
     this.client = client
   }
 
+  /**
+   * This method creates a product tag. It sends a request to the 
+   * [Create Product Tag](https://docs.medusajs.com/api/admin#product-tags_postproducttags)
+   * API route.
+   * 
+   * @param body - The details of the product tag.
+   * @param query - Configure the fields to retrieve in the product tag.
+   * @param headers - Headers to pass in the request
+   * @returns The product tag's details.
+   * 
+   * @example
+   * sdk.admin.productTag.create({
+   *   value: "shirt"
+   * })
+   * .then(({ product_tag }) => {
+   *   console.log(product_tag)
+   * })
+   */
   async create(
     body: HttpTypes.AdminCreateProductTag,
     query?: HttpTypes.AdminProductTagParams,
@@ -30,6 +48,25 @@ export class ProductTag {
     )
   }
 
+  /**
+   * This method updates a tag's details. It sends a request to the
+   * [Update Product Tag](https://docs.medusajs.com/api/admin#product-tags_postproducttagsid)
+   * API route.
+   * 
+   * @param id - The tag's ID.
+   * @param body - The data to update in the tag.
+   * @param query - Configure the fields to retrieve in the product tag.
+   * @param headers - Headers to pass in the request
+   * @returns The product tag's details.
+   * 
+   * @example
+   * sdk.admin.productTag.update("ptag_123", {
+   *   value: "shirt"
+   * })
+   * .then(({ product_tag }) => {
+   *   console.log(product_tag)
+   * })
+   */
   async update(
     id: string,
     body: HttpTypes.AdminUpdateProductTag,
@@ -47,6 +84,52 @@ export class ProductTag {
     )
   }
 
+  /**
+   * This method retrieves a paginated list of product tags. It sends a request to the 
+   * [List Product Tags](https://docs.medusajs.com/api/admin#product-tags_getproducttags) API route.
+   * 
+   * @param query - Filters and pagination configurations.
+   * @param headers - Headers to pass in the request.
+   * @returns The paginated list of product tags.
+   * 
+   * @example
+   * To retrieve the list of product tags:
+   * 
+   * ```ts
+   * sdk.admin.productTag.list()
+   * .then(({ product_tags, count, limit, offset }) => {
+   *   console.log(product_tags)
+   * })
+   * ```
+   * 
+   * To configure the pagination, pass the `limit` and `offset` query parameters.
+   * 
+   * For example, to retrieve only 10 items and skip 10 items:
+   * 
+   * ```ts
+   * sdk.admin.productTag.list({
+   *   limit: 10,
+   *   offset: 10
+   * })
+   * .then(({ product_tags, count, limit, offset }) => {
+   *   console.log(product_tags)
+   * })
+   * ```
+   * 
+   * Using the `fields` query parameter, you can specify the fields and relations to retrieve
+   * in each product tag:
+   * 
+   * ```ts
+   * sdk.admin.productTag.list({
+   *   fields: "id,*products"
+   * })
+   * .then(({ product_tags, count, limit, offset }) => {
+   *   console.log(product_tags)
+   * })
+   * ```
+   * 
+   * Learn more about the `fields` property in the [API reference](https://docs.medusajs.com/api/store#select-fields-and-relations).
+   */
   async list(
     query?: HttpTypes.AdminProductTagListParams,
     headers?: ClientHeaders
@@ -60,6 +143,38 @@ export class ProductTag {
     )
   }
 
+  /**
+   * This method retrieves a product tag by its ID. It sends a request to the 
+   * [Get Product Tag](https://docs.medusajs.com/api/admin#product-tags_getproducttagsid) API route.
+   * 
+   * @param id - The product tag's ID.
+   * @param query - Configure the fields to retrieve in the product tag.
+   * @param headers - Headers to pass in the request
+   * @returns The product tag's details.
+   * 
+   * @example
+   * To retrieve a product tag by its ID:
+   * 
+   * ```ts
+   * sdk.admin.productTag.retrieve("ptag_123")
+   * .then(({ product_tag }) => {
+   *   console.log(product_tag)
+   * })
+   * ```
+   * 
+   * To specify the fields and relations to retrieve:
+   * 
+   * ```ts
+   * sdk.admin.productTag.retrieve("ptag_123", {
+   *   fields: "id,*products"
+   * })
+   * .then(({ product_tag }) => {
+   *   console.log(product_tag)
+   * })
+   * ```
+   * 
+   * Learn more about the `fields` property in the [API reference](https://docs.medusajs.com/api/store#select-fields-and-relations).
+   */
   async retrieve(
     id: string,
     query?: HttpTypes.AdminProductTagParams,
@@ -74,6 +189,21 @@ export class ProductTag {
     )
   }
 
+  /**
+   * This method deletes a product tag. It sends a request to the
+   * [Delete Product Tag](https://docs.medusajs.com/api/admin#product-tags_deleteproducttagsid)
+   * API route.
+   * 
+   * @param id - The tag's ID.
+   * @param headers - Headers to pass in the request
+   * @returns The deletion's details.
+   * 
+   * @example
+   * sdk.admin.productTag.delete("ptag_123")
+   * .then(({ deleted }) => {
+   *   console.log(deleted)
+   * })
+   */
   async delete(id: string, headers?: ClientHeaders) {
     return this.client.fetch<HttpTypes.AdminProductTagDeleteResponse>(
       `/admin/product-tags/${id}`,

packages/core/js-sdk/src/admin/product-type.ts

@@ -14,6 +14,24 @@ export class ProductType {
     this.client = client
   }
 
+  /**
+   * This method creates a product type. It sends a request to the
+   * [Create Product Type](https://docs.medusajs.com/api/admin#product-types_postproducttypes)
+   * API route.
+   * 
+   * @param body - The product type's details.
+   * @param query - Configure the fields to retrieve in the product type.
+   * @param headers - Headers to pass in the request
+   * @returns The product type's details.
+   * 
+   * @example
+   * sdk.admin.productType.create({
+   *   value: "Clothes"
+   * })
+   * .then(({ product_type }) => {
+   *   console.log(product_type)
+   * })
+   */
   async create(
     body: HttpTypes.AdminCreateProductType,
     query?: HttpTypes.SelectParams,
@@ -30,6 +48,25 @@ export class ProductType {
     )
   }
 
+  /**
+   * This method updates a product type. It sends a request to the
+   * [Update Product Type](https://docs.medusajs.com/api/admin#product-types_postproducttypesid)
+   * API route.
+   * 
+   * @param id - The product type's ID.
+   * @param body - The data to update in the product type.
+   * @param query - Configure the fields to retrieve in the product type.
+   * @param headers - Headers to pass in the request
+   * @returns The product type's details.
+   * 
+   * @example
+   * sdk.admin.productType.update("ptyp_123", {
+   *   value: "Clothes"
+   * })
+   * .then(({ product_type }) => {
+   *   console.log(product_type)
+   * })
+   */
   async update(
     id: string,
     body: HttpTypes.AdminUpdateProductType,
@@ -47,6 +84,52 @@ export class ProductType {
     )
   }
 
+  /**
+   * This method retrieves a paginated list of product types. It sends a request to the 
+   * [List Product Types](https://docs.medusajs.com/api/admin#product-types_getproducttypes) API route.
+   * 
+   * @param query - Filters and pagination configurations.
+   * @param headers - Headers to pass in the request.
+   * @returns The paginated list of product types.
+   * 
+   * @example
+   * To retrieve the list of product types:
+   * 
+   * ```ts
+   * sdk.admin.productType.list()
+   * .then(({ product_types, count, limit, offset }) => {
+   *   console.log(product_types)
+   * })
+   * ```
+   * 
+   * To configure the pagination, pass the `limit` and `offset` query parameters.
+   * 
+   * For example, to retrieve only 10 items and skip 10 items:
+   * 
+   * ```ts
+   * sdk.admin.productType.list({
+   *   limit: 10,
+   *   offset: 10
+   * })
+   * .then(({ product_types, count, limit, offset }) => {
+   *   console.log(product_types)
+   * })
+   * ```
+   * 
+   * Using the `fields` query parameter, you can specify the fields and relations to retrieve
+   * in each product type:
+   * 
+   * ```ts
+   * sdk.admin.productType.list({
+   *   fields: "id,*products"
+   * })
+   * .then(({ product_types, count, limit, offset }) => {
+   *   console.log(product_types)
+   * })
+   * ```
+   * 
+   * Learn more about the `fields` property in the [API reference](https://docs.medusajs.com/api/store#select-fields-and-relations).
+   */
   async list(
     query?: HttpTypes.AdminProductTypeListParams,
     headers?: ClientHeaders
@@ -60,6 +143,39 @@ export class ProductType {
     )
   }
 
+  /**
+   * This method retrieves a product type by its ID. It sends a request to the 
+   * [Get Product Type](https://docs.medusajs.com/api/admin#product-types_getproducttypesid)
+   * API route.
+   * 
+   * @param id - The product type's ID.
+   * @param query - Configure the fields to retrieve in the product type.
+   * @param headers - Headers to pass in the request
+   * @returns The product type's details.
+   * 
+   * @example
+   * To retrieve a product type by its ID:
+   * 
+   * ```ts
+   * sdk.admin.productType.retrieve("ptyp_123")
+   * .then(({ product_type }) => {
+   *   console.log(product_type)
+   * })
+   * ```
+   * 
+   * To specify the fields and relations to retrieve:
+   * 
+   * ```ts
+   * sdk.admin.productType.retrieve("ptyp_123", {
+   *   fields: "id,*products"
+   * })
+   * .then(({ product_type }) => {
+   *   console.log(product_type)
+   * })
+   * ```
+   * 
+   * Learn more about the `fields` property in the [API reference](https://docs.medusajs.com/api/store#select-fields-and-relations).
+   */
   async retrieve(
     id: string,
     query?: HttpTypes.AdminProductTypeParams,
@@ -74,6 +190,21 @@ export class ProductType {
     )
   }
 
+  /**
+   * This method deletes a product type. It sends a request to the 
+   * [Delete Product Type](https://docs.medusajs.com/api/admin#product-types_deleteproducttypesid)
+   * API route.
+   * 
+   * @param id - The product type's ID.
+   * @param headers - Headers to pass in the request
+   * @returns The product type's details.
+   * 
+   * @example
+   * sdk.admin.productType.delete("ptyp_123")
+   * .then(({ deleted }) => {
+   *   console.log(deleted)
+   * })
+   */
   async delete(id: string, headers?: ClientHeaders) {
     return this.client.fetch<HttpTypes.AdminProductTypeDeleteResponse>(
       `/admin/product-types/${id}`,

packages/core/js-sdk/src/admin/product-variant.ts

@@ -14,15 +14,62 @@ export class ProductVariant {
     this.client = client
   }
 
+  /**
+   * This method retrieves a paginated list of product variants. It sends a request to the 
+   * [List Product Variants](https://docs.medusajs.com/api/admin#product-variants_getproductvariants)
+   * API route.
+   * 
+   * @param query - Filters and pagination configurations.
+   * @param headers - Headers to pass in the request.
+   * @returns The paginated list of product variants.
+   * 
+   * @example
+   * To retrieve the list of product variants:
+   * 
+   * ```ts
+   * sdk.admin.productVariant.list()
+   * .then(({ variants, count, limit, offset }) => {
+   *   console.log(variants)
+   * })
+   * ```
+   * 
+   * To configure the pagination, pass the `limit` and `offset` query parameters.
+   * 
+   * For example, to retrieve only 10 items and skip 10 items:
+   * 
+   * ```ts
+   * sdk.admin.productVariant.list({
+   *   limit: 10,
+   *   offset: 10
+   * })
+   * .then(({ variants, count, limit, offset }) => {
+   *   console.log(variants)
+   * })
+   * ```
+   * 
+   * Using the `fields` query parameter, you can specify the fields and relations to retrieve
+   * in each campaign:
+   * 
+   * ```ts
+   * sdk.admin.productVariant.list({
+   *   fields: "id,products"
+   * })
+   * .then(({ variants, count, limit, offset }) => {
+   *   console.log(variants)
+   * })
+   * ```
+   * 
+   * Learn more about the `fields` property in the [API reference](https://docs.medusajs.com/api/store#select-fields-and-relations).
+   */
   async list(
-    queryParams?: HttpTypes.AdminProductVariantParams,
+    query?: HttpTypes.AdminProductVariantParams,
     headers?: ClientHeaders
   ) {
     return await this.client.fetch<HttpTypes.AdminProductVariantListResponse>(
       `/admin/product-variants`,
       {
         headers,
-        query: queryParams,
+        query,
       }
     )
   }

packages/core/js-sdk/src/admin/product.ts

@@ -14,6 +14,27 @@ export class Product {
     this.client = client
   }
 
+  /**
+   * This method creates a product import. The products are only imported after
+   * the import is confirmed using the {@link confirmImport} method.
+   * 
+   * This method sends a request to the 
+   * [Create Product Import](https://docs.medusajs.com/api/admin#products_postproductsimport)
+   * API route.
+   * 
+   * @param body - The import's details.
+   * @param query - Query parameters to pass to the request.
+   * @param headers - Headers to pass in the request.
+   * @returns The import's details.
+   * 
+   * @example
+   * sdk.admin.product.import({
+   *   file // uploaded File instance
+   * })
+   * .then(({ transaction_id }) => {
+   *   console.log(transaction_id)
+   * })
+   */
   async import(
     body: HttpTypes.AdminImportProductRequest,
     query?: {},
@@ -37,6 +58,23 @@ export class Product {
     )
   }
 
+  /**
+   * This method confirms a product import created using the method {@link import}.
+   * It sends a request to the 
+   * [Confirm Product Import](https://docs.medusajs.com/api/admin#products_postproductsimporttransaction_idconfirm)
+   * API route.
+   * 
+   * @param transactionId - The ID of the transaction of the created product import. This is returned
+   * by the API route used to create the product import.
+   * @param query - Query parameters to pass in the request.
+   * @param headers - Headers to pass in the request.
+   * 
+   * @example
+   * sdk.admin.product.confirmImport("transaction_123")
+   * .then(() => {
+   *   console.log("Import confirmed")
+   * })
+   */
   async confirmImport(
     transactionId: string,
     query?: {},
@@ -53,6 +91,31 @@ export class Product {
     )
   }
 
+  /**
+   * This method starts a product export process to retrieve a CSV of exported products.
+   * 
+   * You'll receive in the response the transaction ID of the workflow generating the CSV file. 
+   * To check the status of the execution, send a `GET` request to 
+   * `/admin/workflows-executions/export-products/:transaction-id`. 
+   * 
+   * Once the execution finishes successfully, a notification is created for the export. 
+   * You can retrieve the notifications using the `/admin/notification` API route to 
+   * retrieve the file's download URL.
+   * 
+   * This method sends a request to the [Export Product](https://docs.medusajs.com/api/admin#products_postproductsexport)
+   * API route.
+   * 
+   * @param body - The export's details.
+   * @param query - Filters to specify which products to export.
+   * @param headers - Headers to pass in the request. 
+   * @returns The export's details.
+   * 
+   * @example
+   * sdk.admin.product.export({})
+   * .then(({ transaction_id }) => {
+   *   console.log(transaction_id)
+   * })
+   */
   async export(
     body: HttpTypes.AdminExportProductRequest,
     query?: HttpTypes.AdminProductListParams,
@@ -69,6 +132,46 @@ export class Product {
     )
   }
 
+  /**
+   * This method manages products to create, update, or delete them. It sends a request to the 
+   * [Manage Products](https://docs.medusajs.com/api/admin#products_postproductsbatch)
+   * API route.
+   * 
+   * @param body - The products to create, update, or delete.
+   * @param query - Configure the fields to retrieve in the products.
+   * @param headers - Headers to pass in the request
+   * @returns The batch operations details.
+   * 
+   * @example
+   * sdk.admin.product.batch({
+   *   create: [
+   *     {
+   *       title: "Shirt",
+   *       options: [{
+   *         title: "Default",
+   *         values: ["Default Option"]
+   *       }],
+   *       variants: [
+   *         {
+   *           title: "Default",
+   *           options: {
+   *             Default: "Default Option"
+   *           },
+   *           prices: []
+   *         }
+   *       ]
+   *     }
+   *   ],
+   *   update: [{
+   *     id: "prod_123",
+   *     title: "Pants"
+   *   }],
+   *   delete: ["prod_321"]
+   * })
+   * .then(({ created, updated, deleted }) => {
+   *   console.log(created, updated, deleted)
+   * })
+   */
   async batch(
     body: HttpTypes.AdminBatchProductRequest,
     query?: SelectParams,
@@ -85,6 +188,37 @@ export class Product {
     )
   }
 
+  /**
+   * This method creates a product. It sends a request to the 
+   * [Create Product](https://docs.medusajs.com/api/admin#products_postproducts)
+   * API route.
+   * 
+   * @param body - The product's details.
+   * @param query - Configure the fields to retrieve in the product.
+   * @param headers - Headers to pass in the request
+   * @returns The product's details.
+   * 
+   * @example
+   * sdk.admin.product.create({
+   *   title: "Shirt",
+   *   options: [{
+   *     title: "Default",
+   *     values: ["Default Option"]
+   *   }],
+   *   variants: [
+   *     {
+   *       title: "Default",
+   *       options: {
+   *         Default: "Default Option"
+   *       },
+   *       prices: []
+   *     }
+   *   ]
+   * })
+   * .then(({ product }) => {
+   *   console.log(product)
+   * })
+   */
   async create(
     body: HttpTypes.AdminCreateProduct,
     query?: SelectParams,
@@ -100,6 +234,26 @@ export class Product {
       }
     )
   }
+
+  /**
+   * This method updates a product. It sends a request to the
+   * [Update Product](https://docs.medusajs.com/api/admin#products_postproductsid)
+   * API route.
+   * 
+   * @param id - The product's ID.
+   * @param body - The data to update in the product.
+   * @param query - Configure the fields to retrieve in the product.
+   * @param headers - Headers to pass in the request
+   * @returns The product's details.
+   * 
+   * @example
+   * sdk.admin.product.update("prod_123", {
+   *   title: "Shirt",
+   * })
+   * .then(({ product }) => {
+   *   console.log(product)
+   * })
+   */
   async update(
     id: string,
     body: HttpTypes.AdminUpdateProduct,
@@ -116,6 +270,53 @@ export class Product {
       }
     )
   }
+
+  /**
+   * This method retrieves a paginated list of products. It sends a request to the 
+   * [List Products](https://docs.medusajs.com/api/admin#products_getproducts) API route.
+   * 
+   * @param query - Filters and pagination configurations.
+   * @param headers - Headers to pass in the request.
+   * @returns The paginated list of products.
+   * 
+   * @example
+   * To retrieve the list of products:
+   * 
+   * ```ts
+   * sdk.admin.product.list()
+   * .then(({ products, count, limit, offset }) => {
+   *   console.log(products)
+   * })
+   * ```
+   * 
+   * To configure the pagination, pass the `limit` and `offset` query parameters.
+   * 
+   * For example, to retrieve only 10 items and skip 10 items:
+   * 
+   * ```ts
+   * sdk.admin.product.list({
+   *   limit: 10,
+   *   offset: 10
+   * })
+   * .then(({ products, count, limit, offset }) => {
+   *   console.log(products)
+   * })
+   * ```
+   * 
+   * Using the `fields` query parameter, you can specify the fields and relations to retrieve
+   * in each products:
+   * 
+   * ```ts
+   * sdk.admin.product.list({
+   *   fields: "id,*variants"
+   * })
+   * .then(({ products, count, limit, offset }) => {
+   *   console.log(products)
+   * })
+   * ```
+   * 
+   * Learn more about the `fields` property in the [API reference](https://docs.medusajs.com/api/store#select-fields-and-relations).
+   */
   async list(
     queryParams?: HttpTypes.AdminProductListParams,
     headers?: ClientHeaders
@@ -128,6 +329,40 @@ export class Product {
       }
     )
   }
+
+  /**
+   * This method retrieves a product by its ID. It sends a request to the 
+   * [Get Product](https://docs.medusajs.com/api/admin#products_getproductsid)
+   * API route.
+   * 
+   * @param id - The product's ID.
+   * @param query - Configure the fields to retrieve in the product.
+   * @param headers - Headers to pass in the request
+   * @returns The product's details.
+   * 
+   * @example
+   * To retrieve a product by its ID:
+   * 
+   * ```ts
+   * sdk.admin.product.retrieve("prod_123")
+   * .then(({ product }) => {
+   *   console.log(product)
+   * })
+   * ```
+   * 
+   * To specify the fields and relations to retrieve:
+   * 
+   * ```ts
+   * sdk.admin.product.retrieve("prod_123", {
+   *   fields: "id,*variants"
+   * })
+   * .then(({ product }) => {
+   *   console.log(product)
+   * })
+   * ```
+   * 
+   * Learn more about the `fields` property in the [API reference](https://docs.medusajs.com/api/store#select-fields-and-relations).
+   */
   async retrieve(id: string, query?: SelectParams, headers?: ClientHeaders) {
     return await this.client.fetch<HttpTypes.AdminProductResponse>(
       `/admin/products/${id}`,
@@ -137,6 +372,22 @@ export class Product {
       }
     )
   }
+
+  /**
+   * This method deletes a product. It sends a request to the
+   * [Delete Product](https://docs.medusajs.com/api/admin#products_deleteproductsid)
+   * API route.
+   * 
+   * @param id - The product's ID.
+   * @param headers - Headers to pass in the request
+   * @returns The deletion's details.
+   * 
+   * @example
+   * sdk.admin.product.delete("prod_123")
+   * .then(({ deleted }) => {
+   *   console.log(deleted)
+   * })
+   */
   async delete(id: string, headers?: ClientHeaders) {
     return await this.client.fetch<HttpTypes.AdminProductDeleteResponse>(
       `/admin/products/${id}`,
@@ -147,6 +398,40 @@ export class Product {
     )
   }
 
+  /**
+   * This method manages the variants of a product. It sends a request to the
+   * [Manage Variants](https://docs.medusajs.com/api/admin#products_postproductsidvariantsbatch)
+   * API route.
+   * 
+   * @param productId - The product's ID.
+   * @param body - The variants to create, update, or delete.
+   * @param query - Configure the fields to retrieve in the product variants.
+   * @param headers - Headers to pass in the request
+   * @returns The product variants' details.
+   * 
+   * @example
+   * sdk.admin.product.batchVariants("prod_123", {
+   *   create: [
+   *     {
+   *       title: "Blue Shirt",
+   *       options: {
+   *         Color: "Blue"
+   *       },
+   *       prices: []
+   *     }
+   *   ],
+   *   update: [
+   *     {
+   *       id: "variant_123",
+   *       title: "Pants"
+   *     }
+   *   ],
+   *   delete: ["variant_123"]
+   * })
+   * .then(({ created, updated, deleted }) => {
+   *   console.log(created, updated, deleted)
+   * })
+   */
   async batchVariants(
     productId: string,
     body: HttpTypes.AdminBatchProductVariantRequest,
@@ -164,6 +449,34 @@ export class Product {
     )
   }
 
+  /**
+   * This method creates a variant for a product. It sends a request to the
+   * [Create Variant](https://docs.medusajs.com/api/admin#products_postproductsidvariants)
+   * API route.
+   * 
+   * @param productId - The product's ID.
+   * @param body - The variant's details.
+   * @param query - Configure the fields to retrieve in the product.
+   * @param headers - Headers to pass in the request
+   * @returns The product's details.
+   * 
+   * @example
+   * sdk.admin.product.createVariant("prod_123", {
+   *   title: "Blue Shirt",
+   *   options: {
+   *     Color: "Blue"
+   *   },
+   *   prices: [
+   *     {
+   *       amount: 10,
+   *       currency_code: "usd"
+   *     }
+   *   ]
+   * })
+   * .then(({ product }) => {
+   *   console.log(product)
+   * })
+   */
   async createVariant(
     productId: string,
     body: HttpTypes.AdminCreateProductVariant,
@@ -181,6 +494,30 @@ export class Product {
     )
   }
 
+  /**
+   * This method updates a variant of a product. It sends a request to the
+   * [Update Variant](https://docs.medusajs.com/api/admin#products_postproductsidvariantsvariant_id)
+   * API route.
+   * 
+   * @param productId - The product's ID.
+   * @param id - The variant's ID.
+   * @param body - The data to update in the variant.
+   * @param query - Configure the fields to retrieve in the product.
+   * @param headers - Headers to pass in the request
+   * @returns The product's details.
+   * 
+   * @example
+   * sdk.admin.product.updateVariant(
+   *   "prod_123", 
+   *   "variant_123",
+   *     {
+   *     title: "Blue Shirt",
+   *   }
+   * )
+   * .then(({ product }) => {
+   *   console.log(product)
+   * })
+   */
   async updateVariant(
     productId: string,
     id: string,
@@ -199,20 +536,108 @@ export class Product {
     )
   }
 
+  /**
+   * This method retrieves a paginated list of products. It sends a request to the 
+   * [List Products](https://docs.medusajs.com/api/admin#products_getproductsidvariants) API route.
+   * 
+   * @param productId - The ID of the product to retrieve its variants.
+   * @param query - Filters and pagination configurations.
+   * @param headers - Headers to pass in the request.
+   * @returns The paginated list of product variants.
+   * 
+   * @example
+   * To retrieve the list of product variants:
+   * 
+   * ```ts
+   * sdk.admin.product.listVariants("prod_123")
+   * .then(({ variants, count, limit, offset }) => {
+   *   console.log(variants)
+   * })
+   * ```
+   * 
+   * To configure the pagination, pass the `limit` and `offset` query parameters.
+   * 
+   * For example, to retrieve only 10 items and skip 10 items:
+   * 
+   * ```ts
+   * sdk.admin.product.listVariants("prod_123", {
+   *   limit: 10,
+   *   offset: 10
+   * })
+   * .then(({ variants, count, limit, offset }) => {
+   *   console.log(variants)
+   * })
+   * ```
+   * 
+   * Using the `fields` query parameter, you can specify the fields and relations to retrieve
+   * in each product variant:
+   * 
+   * ```ts
+   * sdk.admin.product.listVariants("prod_123", {
+   *   fields: "id,*product"
+   * })
+   * .then(({ variants, count, limit, offset }) => {
+   *   console.log(variants)
+   * })
+   * ```
+   * 
+   * Learn more about the `fields` property in the [API reference](https://docs.medusajs.com/api/store#select-fields-and-relations).
+   */
   async listVariants(
     productId: string,
-    queryParams?: HttpTypes.AdminProductVariantParams,
+    query?: HttpTypes.AdminProductVariantParams,
     headers?: ClientHeaders
   ) {
     return await this.client.fetch<HttpTypes.AdminProductVariantListResponse>(
       `/admin/products/${productId}/variants`,
       {
         headers,
-        query: queryParams,
+        query,
       }
     )
   }
 
+  /**
+   * This method retrieves a product's variant. It sends a request to the
+   * [Retrieve Variant](https://docs.medusajs.com/api/admin#products_getproductsidvariantsvariant_id)
+   * API route.
+   * 
+   * @param productId - The product's ID.
+   * @param id - The variant's ID.
+   * @param query - Configure the fields to retrieve in the product variant.
+   * @param headers - Headers to pass in the request
+   * @returns The product variant's details.
+   * 
+   * @example
+   * To retrieve a product variant by its ID:
+   * 
+   * ```ts
+   * sdk.admin.product.retrieveVariant(
+   *   "prod_123",
+   *   "variant_123"
+   * )
+   * .then(({ variant }) => {
+   *   console.log(variant)
+   * })
+   * ```
+   * 
+   * To specify the fields and relations to retrieve:
+   * 
+   * ```ts
+   * sdk.admin.product.retrieveVariant(
+   *   "prod_123",
+   *   "variant_123",
+   *   {
+   *     fields: "id, *product"
+   *   }
+   * )
+   * .then(({ variant }) => {
+   *   console.log(variant)
+   * })
+   * ```
+   * 
+   * Learn more about the `fields` property in the [API reference](https://docs.medusajs.com/api/store#select-fields-and-relations).
+   */
   async retrieveVariant(
     productId: string,
     id: string,
@@ -228,6 +653,22 @@ export class Product {
     )
   }
 
+  /**
+   * This method deletes a product's variant. It sends a request to the
+   * [Delete Variant](https://docs.medusajs.com/api/admin#products_deleteproductsidvariantsvariant_id)
+   * API route.
+   * 
+   * @param productId - The product's ID.
+   * @param id - The ID of the variant.
+   * @param headers - Headers to pass in the request
+   * @returns The deletion's details.
+   * 
+   * @example
+   * sdk.admin.product.deleteVariant("prod_123", "variant_123")
+   * .then(({ deleted }) => {
+   *   console.log(deleted)
+   * })
+   */
   async deleteVariant(productId: string, id: string, headers?: ClientHeaders) {
     return await this.client.fetch<HttpTypes.AdminProductVariantDeleteResponse>(
       `/admin/products/${productId}/variants/${id}`,
@@ -238,6 +679,50 @@ export class Product {
     )
   }
 
+  /**
+   * This method manages a product's variant's inventories to associate them with inventory items, 
+   * update their inventory items, or delete their association with inventory items.
+   * 
+   * It sends a request to the 
+   * [Manage Variant Inventory](https://docs.medusajs.com/api/admin#products_postproductsidvariantsinventoryitemsbatch)
+   * API route.
+   * 
+   * @param productId - The ID of the product that the variant belongs to.
+   * @param body - The inventory items to create, update, or delete.
+   * @param query - Pass query parameters in the request.
+   * @param headers - Headers to pass in the request
+   * @returns The details of the created, updated, or deleted inventory items.
+   * 
+   * @example
+   * sdk.admin.product.batchVariantInventoryItems(
+   *   "prod_123", 
+   *   {
+   *     create: [
+   *       {
+   *         inventory_item_id: "iitem_123",
+   *         variant_id: "variant_123",
+   *         required_quantity: 10
+   *       }
+   *     ],
+   *     update: [
+   *       {
+   *         inventory_item_id: "iitem_1234",
+   *         variant_id: "variant_1234",
+   *         required_quantity: 20
+   *       }
+   *     ],
+   *     delete: [
+   *       {
+   *         inventory_item_id: "iitem_321",
+   *         variant_id: "variant_321"
+   *       }
+   *     ]
+   *   }
+   * )
+   * .then(({ created, updated, deleted }) => {
+   *   console.log(created, updated, deleted)
+   * })
+   */
   async batchVariantInventoryItems(
     productId: string,
     body: HttpTypes.AdminBatchProductVariantInventoryItemRequest,
@@ -255,6 +740,29 @@ export class Product {
     )
   }
 
+  /**
+   * This method creates an option in a product. It sends a request to the
+   * [Create Option](https://docs.medusajs.com/api/admin#products_postproductsidoptions)
+   * API route.
+   * 
+   * @param productId - The product's ID.
+   * @param body - The option's details.
+   * @param query - Configure the fields to retrieve in the product.
+   * @param headers - Headers to pass in the request
+   * @returns The product's details.
+   * 
+   * @example
+   * sdk.admin.product.createOption(
+   *   "prod_123", 
+   *   {
+   *     title: "Color",
+   *     values: ["Green", "Blue"]
+   *   }
+   * )
+   * .then(({ product }) => {
+   *   console.log(product)
+   * })
+   */
   async createOption(
     productId: string,
     body: HttpTypes.AdminCreateProductOption,
@@ -272,6 +780,30 @@ export class Product {
     )
   }
 
+  /**
+   * This method updates a product's option. It sends a request to the
+   * [Update Option](https://docs.medusajs.com/api/admin#products_postproductsidoptionsoption_id)
+   * API route.
+   * 
+   * @param productId - The product's ID.
+   * @param id - The ID of the option to update.
+   * @param body - The data to update in the option.
+   * @param query - Configure the fields to retrieve in the product.
+   * @param headers - Headers to pass in the request
+   * @returns The product's details.
+   * 
+   * @example
+   * sdk.admin.product.updateOption(
+   *   "prod_123", 
+   *   "prodopt_123",
+   *   {
+   *     title: "Color"
+   *   }
+   * )
+   * .then(({ product }) => {
+   *   console.log(product)
+   * })
+   */
   async updateOption(
     productId: string,
     id: string,
@@ -290,20 +822,108 @@ export class Product {
     )
   }
 
+  /**
+   * This method retrieves a paginated list of product options. It sends a request to the 
+   * [List Options](https://docs.medusajs.com/api/admin#products_getproductsidoptions) API route.
+   * 
+   * @param productId - The ID of the product to retrieve its options
+   * @param query - Filters and pagination configurations.
+   * @param headers - Headers to pass in the request.
+   * @returns The paginated list of product options.
+   * 
+   * @example
+   * To retrieve the list of product options:
+   * 
+   * ```ts
+   * sdk.admin.product.listOptions("prod_123")
+   * .then(({ product_options, count, limit, offset }) => {
+   *   console.log(product_options)
+   * })
+   * ```
+   * 
+   * To configure the pagination, pass the `limit` and `offset` query parameters.
+   * 
+   * For example, to retrieve only 10 items and skip 10 items:
+   * 
+   * ```ts
+   * sdk.admin.product.listOptions("prod_123", {
+   *   limit: 10,
+   *   offset: 10
+   * })
+   * .then(({ product_options, count, limit, offset }) => {
+   *   console.log(product_options)
+   * })
+   * ```
+   * 
+   * Using the `fields` query parameter, you can specify the fields and relations to retrieve
+   * in each product options:
+   * 
+   * ```ts
+   * sdk.admin.product.listOptions("prod_123", {
+   *   fields: "id,title"
+   * })
+   * .then(({ product_options, count, limit, offset }) => {
+   *   console.log(product_options)
+   * })
+   * ```
+   * 
+   * Learn more about the `fields` property in the [API reference](https://docs.medusajs.com/api/store#select-fields-and-relations).
+   */
   async listOptions(
     productId: string,
-    queryParams?: HttpTypes.AdminProductOptionParams,
+    query?: HttpTypes.AdminProductOptionParams,
     headers?: ClientHeaders
   ) {
     return await this.client.fetch<HttpTypes.AdminProductOptionListResponse>(
       `/admin/products/${productId}/options`,
       {
         headers,
-        query: queryParams,
+        query,
       }
     )
   }
 
+  /**
+   * This method retrieves a product's option. It sends a request to the
+   * [Get Option](https://docs.medusajs.com/api/admin#products_getproductsidoptionsoption_id)
+   * API route.
+   * 
+   * @param productId - The product's ID.
+   * @param id - The product option's ID.
+   * @param query - Configure the fields to retrieve in the product option.
+   * @param headers - Headers to pass in the request
+   * @returns The product option's details.
+   * 
+   * @example
+   * To retrieve a product option by its ID:
+   * 
+   * ```ts
+   * sdk.admin.product.retrieveOption(
+   *   "prod_123",
+   *   "prodopt_123"
+   * )
+   * .then(({ product_option }) => {
+   *   console.log(product_option)
+   * })
+   * ```
+   * 
+   * To specify the fields and relations to retrieve:
+   * 
+   * ```ts
+   * sdk.admin.product.retrieveOption(
+   *   "prod_123",
+   *   "prodopt_123",
+   *   {
+   *     fields: "id,title"
+   *   }
+   * )
+   * .then(({ product_option }) => {
+   *   console.log(product_option)
+   * })
+   * ```
+   * 
+   * Learn more about the `fields` property in the [API reference](https://docs.medusajs.com/api/store#select-fields-and-relations).
+   */
   async retrieveOption(
     productId: string,
     id: string,
@@ -319,6 +939,22 @@ export class Product {
     )
   }
 
+  /**
+   * This method deletes a product's option. It sends a request to the 
+   * [Delete Option](https://docs.medusajs.com/api/admin#products_deleteproductsidoptionsoption_id)
+   * API route.
+   * 
+   * @param productId - The product's ID.
+   * @param id - The option's ID.
+   * @param headers - Headers to pass in the request
+   * @returns The deletion's details.
+   * 
+   * @example
+   * sdk.admin.product.deleteOption("prod_123", "prodopt_123")
+   * .then(({ deleted }) => {
+   *   console.log(deleted)
+   * })
+   */
   async deleteOption(productId: string, id: string, headers?: ClientHeaders) {
     return await this.client.fetch<HttpTypes.AdminProductOptionDeleteResponse>(
       `/admin/products/${productId}/options/${id}`,

packages/core/types/src/http/product-tag/admin/payloads.ts

@@ -1,9 +1,21 @@
 export interface AdminCreateProductTag {
+  /**
+   * The tag's value.
+   */
   value: string
+  /**
+   * Key-value pairs of custom data.
+   */
   metadata?: Record<string, unknown> | null
 }
 
 export interface AdminUpdateProductTag {
+  /**
+   * The tag's value.
+   */
   value?: string
+  /**
+   * Key-value pairs of custom data.
+   */
   metadata?: Record<string, unknown> | null
 }

packages/core/types/src/http/product-tag/admin/queries.ts

@@ -5,6 +5,9 @@ import { BaseProductTagListParams } from "../common"
 export interface AdminProductTagListParams
   extends BaseProductTagListParams,
     BaseFilterable<AdminProductTagListParams> {
+  /**
+   * Apply filters on the tag's deletion date.
+   */
   deleted_at?: OperatorMap<string>
 }
 

packages/core/types/src/http/product-tag/admin/responses.ts

@@ -2,11 +2,17 @@ import { DeleteResponse, PaginatedResponse } from "../../common"
 import { AdminProductTag } from "./entities"
 
 export interface AdminProductTagResponse {
+  /**
+   * The tag's details.
+   */
   product_tag: AdminProductTag
 }
 
 export interface AdminProductTagListResponse
   extends PaginatedResponse<{
+    /**
+     * The list of product tags.
+     */
     product_tags: AdminProductTag[]
   }> {}
 

packages/core/types/src/http/product-tag/common.ts

@@ -2,18 +2,51 @@ import { OperatorMap } from "../../dal"
 import { FindParams } from "../common"
 
 export interface BaseProductTag {
+  /**
+   * The tag's ID.
+   */
   id: string
+  /**
+   * The tag's value.
+   */
   value: string
+  /**
+   * The date the tag was created.
+   */
   created_at: string
+  /**
+   * The date the tag was updated.
+   */
   updated_at: string
+  /**
+   * The date the tag was deleted.
+   */
   deleted_at?: string | null
+  /**
+   * Key-value pairs of custom data.
+   */
   metadata?: Record<string, unknown> | null
 }
 
 export interface BaseProductTagListParams extends FindParams {
+  /**
+   * Query or keyword to apply on the tag's searchable fields.
+   */
   q?: string
+  /**
+   * Filter by tag ID(s).
+   */
   id?: string | string[]
+  /**
+   * Filter by value(s).
+   */
   value?: string | string[]
+  /**
+   * Apply filters on the creation date.
+   */
   created_at?: OperatorMap<string>
+  /**
+   * Apply filters on the update date.
+   */
   updated_at?: OperatorMap<string>
 }

packages/core/types/src/http/product-type/admin/payloads.ts

@@ -1,9 +1,21 @@
 export interface AdminCreateProductType {
+  /**
+   * The type's value.
+   */
   value: string
+  /**
+   * Key-value pairs of custom data.
+   */
   metadata?: Record<string, unknown> | null
 }
 
 export interface AdminUpdateProductType {
+  /**
+   * The type's value.
+   */
   value?: string
+  /**
+   * Key-value pairs of custom data.
+   */
   metadata?: Record<string, unknown> | null
 }

packages/core/types/src/http/product-type/admin/queries.ts

@@ -4,11 +4,29 @@ import { FindParams, SelectParams } from "../../common"
 export interface AdminProductTypeListParams
   extends FindParams,
     BaseFilterable<AdminProductTypeListParams> {
+  /**
+   * Query or keywords to apply filters on the type's searchable fields.
+   */
   q?: string
+  /**
+   * Filter by product type ID(s).
+   */
   id?: string | string[]
+  /**
+   * Filter by value(s).
+   */
   value?: string | string[]
+  /**
+   * Apply filters on the creation date.
+   */
   created_at?: OperatorMap<string>
+  /**
+   * Apply filters on the update date.
+   */
   updated_at?: OperatorMap<string>
+  /**
+   * Apply filters on the deletion date.
+   */
   deleted_at?: OperatorMap<string>
 }
 

packages/core/types/src/http/product-type/admin/responses.ts

@@ -2,11 +2,17 @@ import { DeleteResponse, PaginatedResponse } from "../../common"
 import { AdminProductType } from "./entities"
 
 export interface AdminProductTypeResponse {
+  /**
+   * The product type's details.
+   */
   product_type: AdminProductType
 }
 
 export interface AdminProductTypeListResponse
   extends PaginatedResponse<{
+    /**
+     * The list of product types.
+     */
     product_types: AdminProductType[]
   }> {}
 

packages/core/types/src/http/product-type/common.ts

@@ -1,8 +1,26 @@
 export interface BaseProductType {
+  /**
+   * The product type's ID.
+   */
   id: string
+  /**
+   * The product type's value.
+   */
   value: string
+  /**
+   * The date the product type was created.
+   */
   created_at: string
+  /**
+   * The date the product type was updated.
+   */
   updated_at: string
+  /**
+   * The date the product type was deleted.
+   */
   deleted_at?: string | null
+  /**
+   * Key-value pairs of custom data.
+   */
   metadata?: Record<string, unknown> | null
 }

packages/core/types/src/http/product/admin/entitites.ts

@@ -14,27 +14,69 @@ import {
 } from "../common"
 
 export interface AdminProductVariant extends BaseProductVariant {
+  /**
+   * The product variant's prices.
+   */
   prices: AdminPrice[] | null
+  /**
+   * The variant's values for the associated product's options.
+   */
   options: AdminProductOptionValue[] | null
+  /**
+   * The product that this variant belongs to.
+   */
   product?: AdminProduct | null
 }
 export interface AdminProductOption extends BaseProductOption {
+  /**
+   * The associated product's details.
+   */
   product?: AdminProduct | null
+  /**
+   * The option's values.
+   */
   values?: AdminProductOptionValue[]
 }
 export interface AdminProductImage extends BaseProductImage {}
 export interface AdminProductOptionValue extends BaseProductOptionValue {
+  /**
+   * The option's details.
+   */
   option?: AdminProductOption | null
 }
 export interface AdminProduct
   extends Omit<BaseProduct, "categories" | "variants"> {
+  /**
+   * The product's collection.
+   */
   collection?: AdminCollection | null
+  /**
+   * The product's categories.
+   */
   categories?: AdminProductCategory[] | null
+  /**
+   * The sales channels that the product is available in.
+   */
   sales_channels?: AdminSalesChannel[] | null
+  /**
+   * The product's variants.
+   */
   variants: AdminProductVariant[] | null
+  /**
+   * The product's type.
+   */
   type: AdminProductType | null
+  /**
+   * The product's tags.
+   */
   tags?: AdminProductTag[] | null
+  /**
+   * The product's options.
+   */
   options: AdminProductOption[] | null
+  /**
+   * The product's images.
+   */
   images: AdminProductImage[] | null
 }
 export type AdminProductStatus = ProductStatus

packages/core/types/src/http/product/admin/payloads.ts

@@ -3,6 +3,11 @@ import { ProductStatus } from "../common"
 
 export interface AdminExportProductRequest {}
 export interface AdminImportProductRequest {
+  /**
+   * The CSV file to import the products from.
+   * 
+   * It's an uploaded file of type [File](https://developer.mozilla.org/en-US/docs/Web/API/File).
+   */
   file: File
 }
 export interface AdminBatchProductRequest
@@ -22,12 +27,37 @@ export interface AdminBatchProductVariantInventoryItemRequest
   > {}
 
 export interface AdminCreateProductVariantPrice {
+  /**
+   * The price's currency code.
+   * 
+   * @example
+   * usd
+   */
   currency_code: string
+  /**
+   * The price's amount.
+   */
   amount: number
+  /**
+   * The minimum quantity required in the cart for the price to apply.
+   */
   min_quantity?: number | null
+  /**
+   * The maximum quantity required in the cart for the price to apply.
+   */
   max_quantity?: number | null
-  // Note: Although the BE is generic, we only use region_id for price rules for now, so it's better to keep the typings stricter.
+  /**
-  rules?: { region_id: string } | null
+   * The price's rules.
+   * 
+   * @privateRemarks
+   * Note: Although the BE is generic, we only use region_id for price rules for now, so it's better to keep the typings stricter.
+   */
+  rules?: { 
+    /**
+     * The ID of the region that the price applies in.
+     */
+    region_id: string
+  } | null
 }
 
 export interface AdminCreateProductVariantInventoryKit {
@@ -36,135 +66,492 @@ export interface AdminCreateProductVariantInventoryKit {
 }
 
 export interface AdminCreateProductVariant {
+  /**
+   * The variant's title.
+   */
   title: string
+  /**
+   * The variant's SKU.
+   */
   sku?: string
+  /**
+   * The variant's EAN.
+   */
   ean?: string
+  /**
+   * The variant's UPC.
+   */
   upc?: string
+  /**
+   * The variant's barcode.
+   */
   barcode?: string
+  /**
+   * The variant's HS code.
+   */
   hs_code?: string
+  /**
+   * The variant's MID code.
+   */
   mid_code?: string
+  /**
+   * Whether the variant can be ordered even if it's out of stock.
+   */
   allow_backorder?: boolean
+  /**
+   * Whether Medusa manages the variant's inventory. If disabled,
+   * the variant is always considered in stock.
+   */
   manage_inventory?: boolean
+  /**
+   * The variant's ranking among its sibling variants.
+   */
   variant_rank?: number
+  /**
+   * The variant's weight.
+   */
   weight?: number
+  /**
+   * The variant's length.
+   */
   length?: number
+  /**
+   * The variant's height.
+   */
   height?: number
+  /**
+   * The variant's width.
+   */
   width?: number
+  /**
+   * The variant's origin country.
+   */
   origin_country?: string
+  /**
+   * The variant's material.
+   */
   material?: string
+  /**
+   * Key-value pairs of custom data.
+   */
   metadata?: Record<string, unknown>
+  /**
+   * The variant's prices.
+   */
   prices: AdminCreateProductVariantPrice[]
+  /**
+   * The variant's inventory items. It's only
+   * available if `manage_inventory` is enabled.
+   */
   inventory_items?: AdminCreateProductVariantInventoryKit[]
+  /**
+   * The variant's values for the associated product's options.
+   */
   options?: Record<string, string>
 }
 
 export interface AdminCreateProduct {
+  /**
+   * The product's title.
+   */
   title: string
+  /**
+   * The product's subtitle.
+   */
   subtitle?: string
+  /**
+   * The product's description.
+   */
   description?: string
+  /**
+   * Whether the product is a gift card.
+   */
   is_giftcard?: boolean
+  /**
+   * Whether discounts can be applied on the product.
+   */
   discountable?: boolean
-  images?: { url: string }[]
+  /**
+   * The product's images.
+   */
+  images?: { 
+    /**
+     * The image's URL.
+     */
+    url: string 
+  }[]
+  /**
+   * The product's thumbnail URL.
+   */
   thumbnail?: string
+  /**
+   * The product's handle.
+   */
   handle?: string
+  /**
+   * The product's status.
+   */
   status?: ProductStatus
+  /**
+   * The ID of the product's type.
+   */
   type_id?: string
+  /**
+   * The ID of the product in an external or third-party system.
+   */
   external_id?: string
+  /**
+   * The ID of the product's collection.
+   */
   collection_id?: string
-  categories?: { id: string }[]
+  /**
-  tags?: { id: string }[]
+   * The product's categories.
+   */
+  categories?: { 
+    /**
+     * The ID of a product category that the product belongs to.
+     */
+    id: string
+  }[]
+  /**
+   * The product's tags.
+   */
+  tags?: { 
+    /**
+     * The ID of the associated product tag.
+     */
+    id: string
+  }[]
+  /**
+   * The product's options.
+   */
   options: AdminCreateProductOption[]
+  /**
+   * The product's variants.
+   */
   variants?: AdminCreateProductVariant[]
-  sales_channels?: { id: string }[]
+  /**
+   * The sales channels that the product is available in.
+   */
+  sales_channels?: { 
+    /**
+     * The ID of a sales channel that the product is available in.
+     */
+    id: string
+  }[]
+  /**
+   * The product's weight.
+   */
   weight?: number
+  /**
+   * The product's length.
+   */
   length?: number
+  /**
+   * The product's height.
+   */
   height?: number
+  /**
+   * The product's width.
+   */
   width?: number
+  /**
+   * The product's HS code.
+   */
   hs_code?: string
+  /**
+   * The product's MID code.
+   */
   mid_code?: string
+  /**
+   * The product's origin country.
+   */
   origin_country?: string
+  /**
+   * The product's material.
+   */
   material?: string
+  /**
+   * Key-value pairs of custom data.
+   */
   metadata?: Record<string, unknown>
 }
 
 export interface AdminUpdateProductVariant {
+  /**
+   * The variant's title.
+   */
   title?: string
+  /**
+   * The variant's SKU.
+   */
   sku?: string | null
+  /**
+   * The variant's EAN.
+   */
   ean?: string | null
+  /**
+   * The variant's UPC.
+   */
   upc?: string | null
+  /**
+   * The variant's barcode.
+   */
   barcode?: string | null
+  /**
+   * The variant's HS code.
+   */
   hs_code?: string | null
+  /**
+   * The variant's MID code.
+   */
   mid_code?: string | null
+  /**
+   * Whether the variant can be ordered even if it's out of stock.
+   */
   allow_backorder?: boolean
+  /**
+   * Whether Medusa should manage the variant's inventory. If disabled,
+   * the variant is always considered in stock.
+   */
   manage_inventory?: boolean
+  /**
+   * The variant's ranking among its sibling variants.
+   */
   variant_rank?: number
+  /**
+   * The variant's weight.
+   */
   weight?: number | null
+  /**
+   * The variant's length.
+   */
   length?: number | null
+  /**
+   * The variant's height.
+   */
   height?: number | null
+  /**
+   * The variant's width.
+   */
   width?: number | null
+  /**
+   * The variant's origin country.
+   */
   origin_country?: string | null
+  /**
+   * The variant's material.
+   */
   material?: string | null
+  /**
+   * Key-value pairs of custom data.
+   */
   metadata?: Record<string, unknown> | null
+  /**
+   * The variant's prices.
+   */
   prices?: AdminCreateProductVariantPrice[]
+  /**
+   * The variant's values for the associated product's options.
+   */
   options?: Record<string, string>
 }
 
 export interface AdminBatchUpdateProductVariant extends AdminUpdateProductVariant {
+  /**
+   * The ID of the variant to update.
+   */
   id: string
 }
 
 export interface AdminUpdateProduct {
+  /**
+   * The product's title.
+   */
   title?: string
+  /**
+   * The product's subtitle.
+   */
   subtitle?: string | null
+  /**
+   * The product's description.
+   */
   description?: string | null
+  /**
+   * Whether the product is a gift card.
+   */
   is_giftcard?: boolean
+  /**
+   * Whether discounts can be applied on the product.
+   */
   discountable?: boolean
-  images?: { url: string }[]
+  /**
+   * The product's images.
+   */
+  images?: { 
+    /**
+     * The image's URL.
+     */
+    url: string
+  }[]
+  /**
+   * The product's thumbnail URL.
+   */
   thumbnail?: string | null
+  /**
+   * The product's handle.
+   */
   handle?: string
+  /**
+   * The product's status.
+   */
   status?: ProductStatus
+  /**
+   * The ID of the associated product type.
+   */
   type_id?: string | null
+  /**
+   * The ID of the product in an external or third-party system.
+   */
   external_id?: string | null
+  /**
+   * The ID of the associated product collection.
+   */
   collection_id?: string | null
-  categories?: { id: string }[]
+  /**
-  tags?: { id: string }[]
+   * The product's categories.
+   */
+  categories?: { 
+    /**
+     * The ID of the category that the product belongs to.
+     */
+    id: string 
+  }[]
+  /**
+   * The product's tags.
+   */
+  tags?: { 
+    /**
+     * The ID of a tag that the product is associated with.
+     */
+    id: string 
+  }[]
+  /**
+   * The product's options.
+   */
   options?: AdminUpdateProductOption[]
+  /**
+   * The product's variants.
+   */
   variants?: (AdminCreateProductVariant | AdminUpdateProductVariant)[]
-  sales_channels?: { id: string }[]
+  /**
+   * The sales channels that the product is available in.
+   */
+  sales_channels?: { 
+    /**
+     * The ID of a sales channel that the product is available in.
+     */
+    id: string 
+  }[]
+  /**
+   * The product's weight.
+   */
   weight?: number | null
+  /**
+   * The product's length.
+   */
   length?: number | null
+  /**
+   * The product's height.
+   */
   height?: number | null
+  /**
+   * The product's width.
+   */
   width?: number | null
+  /**
+   * The product's HS code.
+   */
   hs_code?: string | null
+  /**
+   * The product's MID code.
+   */
   mid_code?: string | null
+  /**
+   * The product's origin country.
+   */
   origin_country?: string | null
+  /**
+   * The product's material.
+   */
   material?: string | null
+  /**
+   * Key-value pairs of custom data.
+   */
   metadata?: Record<string, unknown> | null
 }
 
 export interface AdminCreateProductOption {
+  /**
+   * The option's title.
+   */
   title: string
+  /**
+   * The option's values.
+   */
   values: string[]
 }
 
 export interface AdminUpdateProductOption {
+  /**
+   * The option's title.
+   */
   title?: string
+  /**
+   * The option's values.
+   */
   values?: string[]
 }
 
 interface AdminCreateProductVariantInventoryItem {
+  /**
+   * The number of units a single quantity is equivalent to. For example, if a customer orders one quantity of the variant, Medusa checks the availability of the quantity multiplied by the
+   * value set for `required_quantity`. When the customer orders the quantity, Medusa reserves the ordered quantity multiplied by the value set for `required_quantity`.
+   */
   required_quantity: number
+  /**
+   * The ID of the inventory item.
+   */
   inventory_item_id: string
+  /**
+   * The ID of the variant.
+   */
   variant_id: string
 }
 
 interface AdminUpdateProductVariantInventoryItem {
+  /**
+   * The number of units a single quantity is equivalent to. For example, if a customer orders one quantity of the variant, Medusa checks the availability of the quantity multiplied by the
+   * value set for `required_quantity`. When the customer orders the quantity, Medusa reserves the ordered quantity multiplied by the value set for `required_quantity`.
+   */
   required_quantity: number
+  /**
+   * The ID of the inventory item.
+   */
   inventory_item_id: string
+  /**
+   * The ID of the variant.
+   */
   variant_id: string
 }
 
 interface AdminDeleteProductVariantInventoryItem {
+  /**
+   * The ID of the inventory.
+   */
   inventory_item_id: string
+  /**
+   * The ID of the variant.
+   */
   variant_id: string
 }

packages/core/types/src/http/product/admin/queries.ts

@@ -7,16 +7,44 @@ export interface AdminProductOptionParams
 export interface AdminProductVariantParams
   extends FindParams,
     BaseFilterable<AdminProductVariantParams> {
+  /**
+   * Query or keywords to filter the variant's searchable fields.
+   */
   q?: string
+  /**
+   * Filter by variant ID(s).
+   */
   id?: string | string[]
+  /**
+   * Filter by whether Medusa manages the inventory of the variant.
+   */
   manage_inventory?: boolean
+  /**
+   * Filter by whether the variant can be ordered even if it's
+   * out of stock.
+   */
   allow_backorder?: boolean
+  /**
+   * Apply filters on the variant's creation date.
+   */
   created_at?: OperatorMap<string>
+  /**
+   * Apply filters on the variant's update date.
+   */
   updated_at?: OperatorMap<string>
+  /**
+   * Apply filters on the variant's deletion date.
+   */
   deleted_at?: OperatorMap<string>
 }
 export interface AdminProductListParams
   extends Omit<BaseProductListParams, "categories"> {
+  /**
+   * Filter by price list ID(s) to retrieve the associated products only.
+   */
   price_list_id?: string | string[]
+  /**
+   * Apply filters on the product variants.
+   */
   variants?: AdminProductVariantParams
 }

packages/core/types/src/http/product/admin/responses.ts

@@ -13,10 +13,16 @@ import {
 import { AdminInventoryItem } from "../../inventory"
 
 export interface AdminProductResponse {
+  /**
+   * The product's details.
+   */
   product: AdminProduct
 }
 
 export type AdminProductListResponse = PaginatedResponse<{
+  /**
+   * The list of products.
+   */
   products: AdminProduct[]
 }>
 
@@ -30,6 +36,9 @@ export interface AdminProductVariantResponse {
 }
 
 export type AdminProductVariantListResponse = PaginatedResponse<{
+  /**
+   * The list of product variants.
+   */
   variants: AdminProductVariant[]
 }>
 
@@ -37,13 +46,29 @@ export interface AdminProductVariantDeleteResponse
   extends DeleteResponseWithParent<"variant", AdminProduct> {}
 
 export interface AdminExportProductResponse {
+  /**
+   * The ID of the export product workflow's transaction.
+   */
   transaction_id: string
 }
 
 export interface AdminImportProductResponse {
+  /**
+   * The ID of the import product workflow execution's transaction. 
+   * This is useful to confirm the import using the `/admin/products/:transaction-id/import` API route.
+   */
   transaction_id: string
+  /**
+   * Details of the products to create or update when the import is confirmed.
+   */
   summary: {
+    /**
+     * The number of products that will be created by the import.
+     */
     toCreate: number
+    /**
+     * The number of products that will be updated by the import.
+     */
     toUpdate: number
   }
 }
@@ -55,10 +80,16 @@ export interface AdminBatchProductVariantInventoryItemResponse
   extends BatchResponse<AdminInventoryItem> {}
 
 export interface AdminProductOptionResponse {
+  /**
+   * The product option's details.
+   */
   product_option: AdminProductOption
 }
 
 export type AdminProductOptionListResponse = PaginatedResponse<{
+  /**
+   * The list of product options.
+   */
   product_options: AdminProductOption[]
 }>
 

packages/core/types/src/http/product/common.ts

@@ -282,11 +282,29 @@ export interface BaseProductOption {
 }
 
 export interface BaseProductImage {
+  /**
+   * The image's ID.
+   */
   id: string
+  /**
+   * The image's URL.
+   */
   url: string
+  /**
+   * The date the image was created.
+   */
   created_at?: string
+  /**
+   * The date the image was updated.
+   */
   updated_at?: string
+  /**
+   * The date the image was deleted.
+   */
   deleted_at?: string | null
+  /**
+   * Key-value pairs of custom data.
+   */
   metadata?: Record<string, unknown> | null
 }
 

www/utils/generated/oas-output/operations/admin/post_admin_products_[id]_variants_inventory-items_batch.ts

@@ -37,7 +37,8 @@
  *                 required_quantity:
  *                   type: number
  *                   title: required_quantity
- *                   description: The variant's quantity.
+ *                   description: The number of units a single quantity is equivalent to. For example, if a customer orders one quantity of the variant, Medusa checks the availability of the quantity multiplied by the
+ *                     value set for `required_quantity`. When the customer orders the quantity, Medusa reserves the ordered quantity multiplied by the value set for `required_quantity`.
  *                 inventory_item_id:
  *                   type: string
  *                   title: inventory_item_id
@@ -60,7 +61,8 @@
  *                 required_quantity:
  *                   type: number
  *                   title: required_quantity
- *                   description: The variant's quantity.
+ *                   description: The number of units a single quantity is equivalent to. For example, if a customer orders one quantity of the variant, Medusa checks the availability of the quantity multiplied by the
+ *                     value set for `required_quantity`. When the customer orders the quantity, Medusa reserves the ordered quantity multiplied by the value set for `required_quantity`.
  *                 inventory_item_id:
  *                   type: string
  *                   title: inventory_item_id