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

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

* add api route link

packages/core/js-sdk/src/admin/price-list.ts

@@ -15,6 +15,39 @@ export class PriceList {
     this.client = client
   }
 
+  /**
+   * This method retrieves a price list. It sends a request to the
+   * [Get Price List](https://docs.medusajs.com/v2/api/admin#price-lists_getpricelistsid)
+   * API route.
+   * 
+   * @param id - The price list's ID.
+   * @param query - Configure the fields to retrieve in the price list.
+   * @param headers - Headers to pass in the request
+   * @returns The price list's details.
+   * 
+   * @example
+   * To retrieve a price list by its ID:
+   * 
+   * ```ts
+   * sdk.admin.priceList.retrieve("plist_123")
+   * .then(({ price_list }) => {
+   *   console.log(price_list)
+   * })
+   * ```
+   * 
+   * To specify the fields and relations to retrieve:
+   * 
+   * ```ts
+   * sdk.admin.priceList.retrieve("plist_123", {
+   *   fields: "id,*prices"
+   * })
+   * .then(({ price_list }) => {
+   *   console.log(price_list)
+   * })
+   * ```
+   * 
+   * Learn more about the `fields` property in the [API reference](https://docs.medusajs.com/v2/api/store#select-fields-and-relations).
+   */
   async retrieve(
     id: string,
     query?: HttpTypes.AdminPriceListParams,
@@ -30,6 +63,52 @@ export class PriceList {
     )
   }
 
+  /**
+   * This method retrieves a paginated list of price lists. It sends a request to the 
+   * [List Price Lists](https://docs.medusajs.com/v2/api/admin#price-lists_getpricelists) API route.
+   * 
+   * @param query - Filters and pagination configurations.
+   * @param headers - Headers to pass in the request.
+   * @returns The paginated list of price lists.
+   * 
+   * @example
+   * To retrieve the list of price lists:
+   * 
+   * ```ts
+   * sdk.admin.priceList.list()
+   * .then(({ price_lists, count, limit, offset }) => {
+   *   console.log(price_lists)
+   * })
+   * ```
+   * 
+   * 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.priceList.list({
+   *   limit: 10,
+   *   offset: 10
+   * })
+   * .then(({ price_lists, count, limit, offset }) => {
+   *   console.log(price_lists)
+   * })
+   * ```
+   * 
+   * Using the `fields` query parameter, you can specify the fields and relations to retrieve
+   * in each price list:
+   * 
+   * ```ts
+   * sdk.admin.priceList.list({
+   *   fields: "id,*prices"
+   * })
+   * .then(({ price_lists, count, limit, offset }) => {
+   *   console.log(price_lists)
+   * })
+   * ```
+   * 
+   * Learn more about the `fields` property in the [API reference](https://docs.medusajs.com/v2/api/store#select-fields-and-relations).
+   */
   async list(
     query?: HttpTypes.AdminPriceListListParams,
     headers?: ClientHeaders
@@ -44,6 +123,36 @@ export class PriceList {
     )
   }
 
+  /**
+   * This method creates a price list. It sends a request to the
+   * [Create Price List](https://docs.medusajs.com/v2/api/admin#price-lists_postpricelists)
+   * API route.
+   * 
+   * @param body - The details of the price list to create.
+   * @param query - Configure the fields to retrieve in the price list.
+   * @param headers - Headers to pass in the request
+   * @returns The price list's details.
+   * 
+   * @example
+   * sdk.admin.priceList.create({
+   *   title: "My Price List",
+   *   status: "active",
+   *   type: "sale",
+   *   prices: [
+   *     {
+   *       variant_id: "variant_123",
+   *       amount: 10,
+   *       currency_code: "usd",
+   *       rules: {
+   *         region_id: "reg_123"
+   *       }
+   *     }
+   *   ]
+   * })
+   * .then(({ price_list }) => {
+   *   console.log(price_list)
+   * })
+   */
   async create(
     body: HttpTypes.AdminCreatePriceList,
     query?: HttpTypes.AdminPriceListParams,
@@ -60,6 +169,25 @@ export class PriceList {
     )
   }
 
+  /**
+   * This method updates a price list. It sends a request to the 
+   * [Update Price List](https://docs.medusajs.com/v2/api/admin#price-lists_postpricelistsid)
+   * API route.
+   * 
+   * @param id - The price list's ID.
+   * @param body - The data to update in the price list.
+   * @param query - Configure the fields to retrieve in the price list.
+   * @param headers - Headers to pass in the request
+   * @returns The price list's details.
+   * 
+   * @example
+   * sdk.admin.priceList.update("plist_123", {
+   *   title: "My Price List",
+   * })
+   * .then(({ price_list }) => {
+   *   console.log(price_list)
+   * })
+   */
   async update(
     id: string,
     body: HttpTypes.AdminUpdatePriceList,
@@ -77,6 +205,21 @@ export class PriceList {
     )
   }
 
+  /**
+   * This method deletes a price list. It sends a request to the
+   * [Delete Price List](https://docs.medusajs.com/v2/api/admin#price-lists_deletepricelistsid)
+   * API route.
+   * 
+   * @param id - The price list's ID.
+   * @param headers - Headers to pass in the request
+   * @returns The deletion's details.
+   * 
+   * @example
+   * sdk.admin.priceList.delete("plist_123")
+   * .then(({ deleted }) => {
+   *   console.log(deleted)
+   * })
+   */
   async delete(id: string, headers?: ClientHeaders) {
     return this.client.fetch<HttpTypes.AdminPriceListDeleteResponse>(
       `/admin/price-lists/${id}`,
@@ -87,13 +230,45 @@ export class PriceList {
     )
   }
 
+  /**
+   * This method manages the prices of a price list to create, update, or delete them.
+   * It sends a request to the [Manage Prices](https://docs.medusajs.com/v2/api/admin#price-lists_postpricelistsidpricesbatch)
+   * API route.
+   * 
+   * @param id - The price list's ID.
+   * @param body - The prices to create, update, or delete.
+   * @param query - Configure the fields to retrieve in the price list.
+   * @param headers - Headers to pass in the request
+   * @returns The price list's details.
+   * 
+   * @example
+   * sdk.admin.priceList.batchPrices("plist_123", {
+   *   create: [{
+   *     variant_id: "variant_123",
+   *     currency_code: "usd",
+   *     amount: 10,
+   *     rules: {
+   *       region_id: "reg_123"
+   *     }
+   *   }],
+   *   update: [{
+   *     id: "price_123",
+   *     variant_id: "variant_123",
+   *     amount: 20,
+   *   }],
+   *   delete: ["price_123"]
+   * })
+   * .then(({ created, updated, deleted }) => {
+   *   console.log(created, updated, deleted)
+   * })
+   */
   async batchPrices(
     id: string,
     body: HttpTypes.AdminBatchPriceListPrice,
     query?: HttpTypes.AdminPriceListParams,
     headers?: ClientHeaders
   ) {
-    return this.client.fetch<HttpTypes.AdminPriceListResponse>(
+    return this.client.fetch<HttpTypes.AdminPriceListBatchResponse>(
       `/admin/price-lists/${id}/prices/batch`,
       {
         method: "POST",
@@ -104,6 +279,25 @@ export class PriceList {
     )
   }
 
+  /**
+   * This method removes products from a price list. It sends a request to the
+   * [Remove Product](https://docs.medusajs.com/v2/api/admin#price-lists_postpricelistsidproducts)
+   * API route.
+   * 
+   * @param id - The price list's ID.
+   * @param body - The details of the products to remove.
+   * @param query - Configure the fields to retrieve in the price list.
+   * @param headers - Headers to pass in the request
+   * @returns The price list's details.
+   * 
+   * @example
+   * sdk.admin.priceList.linkProducts("plist_123", {
+   *   remove: ["prod_123"]
+   * })
+   * .then(({ price_list }) => {
+   *   console.log(price_list)
+   * })
+   */
   async linkProducts(
     id: string,
     body: HttpTypes.AdminLinkPriceListProducts,

packages/core/js-sdk/src/admin/price-preference.ts

@@ -15,6 +15,39 @@ export class PricePreference {
     this.client = client
   }
 
+  /**
+   * This method retrieves a price preference. It sends a request to the
+   * [Get Price Preference](https://docs.medusajs.com/api/admin#price-preferences_getpricepreferencesid)
+   * API route.
+   * 
+   * @param id - The price preference's ID.
+   * @param query - Configure the fields to retrieve in the price preference.
+   * @param headers - Headers to pass in the request
+   * @returns The price preference's details.
+   * 
+   * @example
+   * To retrieve a price preference by its ID:
+   * 
+   * ```ts
+   * sdk.admin.pricePreference.retrieve("prpref_123")
+   * .then(({ price_preference }) => {
+   *   console.log(price_preference)
+   * })
+   * ```
+   * 
+   * To specify the fields and relations to retrieve:
+   * 
+   * ```ts
+   * sdk.admin.pricePreference.retrieve("prpref_123", {
+   *   fields: "id,is_tax_inclusive"
+   * })
+   * .then(({ price_preference }) => {
+   *   console.log(price_preference)
+   * })
+   * ```
+   * 
+   * 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.AdminPricePreferenceParams,
@@ -30,6 +63,52 @@ export class PricePreference {
     )
   }
 
+  /**
+   * This method retrieves a paginated list of price preferences. It sends a request to the 
+   * [List Price Preferences](https://docs.medusajs.com/api/admin#price-preferences_getpricepreferences) API route.
+   * 
+   * @param query - Filters and pagination configurations.
+   * @param headers - Headers to pass in the request.
+   * @returns The paginated list of price preferences.
+   * 
+   * @example
+   * To retrieve the list of price preferences:
+   * 
+   * ```ts
+   * sdk.admin.pricePreference.list()
+   * .then(({ price_preferences, count, limit, offset }) => {
+   *   console.log(price_preferences)
+   * })
+   * ```
+   * 
+   * 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.pricePreference.list({
+   *   limit: 10,
+   *   offset: 10
+   * })
+   * .then(({ price_preferences, count, limit, offset }) => {
+   *   console.log(price_preferences)
+   * })
+   * ```
+   * 
+   * Using the `fields` query parameter, you can specify the fields and relations to retrieve
+   * in each price preference:
+   * 
+   * ```ts
+   * sdk.admin.pricePreference.list({
+   *   fields: "id,is_tax_inclusive"
+   * })
+   * .then(({ price_preferences, count, limit, offset }) => {
+   *   console.log(price_preferences)
+   * })
+   * ```
+   * 
+   * Learn more about the `fields` property in the [API reference](https://docs.medusajs.com/api/store#select-fields-and-relations).
+   */
   async list(
     query?: HttpTypes.AdminPricePreferenceListParams,
     headers?: ClientHeaders
@@ -44,6 +123,26 @@ export class PricePreference {
     )
   }
 
+  /**
+   * This method creates a price preference. It sends a request to the
+   * [Create Price Preference](https://docs.medusajs.com/api/admin#price-preferences_postpricepreferences)
+   * API route.
+   * 
+   * @param body - The details of the price preference to create.
+   * @param query - Configure the fields to retrieve in the price preference.
+   * @param headers - Headers to pass in the request
+   * @returns The price preference's details.
+   * 
+   * @example
+   * sdk.admin.pricePreference.create({
+   *   attribute: "region_id",
+   *   value: "region_123",
+   *   is_tax_inclusive: true
+   * })
+   * .then(({ price_preference }) => {
+   *   console.log(price_preference)
+   * })
+   */
   async create(
     body: HttpTypes.AdminCreatePricePreference,
     query?: HttpTypes.AdminPricePreferenceParams,
@@ -60,6 +159,25 @@ export class PricePreference {
     )
   }
 
+  /**
+   * This method updates a price preference. It sends a request to the
+   * [Update Price Preference](https://docs.medusajs.com/api/admin#price-preferences_postpricepreferencesid)
+   * API route.
+   * 
+   * @param id - The price preference's ID.
+   * @param body - The data to update in the price preference.
+   * @param query - Configure the fields to retrieve in the price preference.
+   * @param headers - Headers to pass in the request
+   * @returns The price preference's details.
+   * 
+   * @example
+   * sdk.admin.pricePreference.update("prpref_123", {
+   *   is_tax_inclusive: true
+   * })
+   * .then(({ price_preference }) => {
+   *   console.log(price_preference)
+   * })
+   */
   async update(
     id: string,
     body: HttpTypes.AdminUpdatePricePreference,
@@ -77,6 +195,21 @@ export class PricePreference {
     )
   }
 
+  /**
+   * This method deletes a price preference. It sends a request to the
+   * [Delete Price Preference](https://docs.medusajs.com/api/admin#price-preferences_deletepricepreferencesid)
+   * API route.
+   * 
+   * @param id - The price preference's ID.
+   * @param headers - Headers to pass in the request
+   * @returns The deletion's details.
+   * 
+   * @example
+   * sdk.admin.pricePreference.delete("prpref_123")
+   * .then(({ deleted }) => {
+   *   console.log(deleted)
+   * })
+   */
   async delete(id: string, headers?: ClientHeaders) {
     return this.client.fetch<HttpTypes.AdminPricePreferenceDeleteResponse>(
       `/admin/price-preferences/${id}`,

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

@@ -14,6 +14,24 @@ export class ProductCategory {
     this.client = client
   }
 
+  /**
+   * This method creates a product category. It sends a request to the
+   * [Create Category](https://docs.medusajs.com/api/admin#product-categories_postproductcategories)
+   * API route.
+   * 
+   * @param body - The details of the category to create.
+   * @param query - Configure the fields to retrieve in the category.
+   * @param headers - Headers to pass in the request
+   * @returns The category's details.
+   * 
+   * @example
+   * sdk.admin.productCategory.create({
+   *   name: "Shirts"
+   * })
+   * .then(({ product_category }) => {
+   *   console.log(product_category)
+   * })
+   */
   async create(
     body: HttpTypes.AdminCreateProductCategory,
     query?: HttpTypes.AdminProductCategoryParams,
@@ -30,6 +48,25 @@ export class ProductCategory {
     )
   }
 
+  /**
+   * This method updates a product category. It sends a request to the
+   * [Update Category](https://docs.medusajs.com/api/admin#product-categories_postproductcategoriesid)
+   * API route.
+   * 
+   * @param id - The product category's ID.
+   * @param body - The data to update in the category.
+   * @param query - Configure the fields to retrieve in the category.
+   * @param headers - Headers to pass in the request
+   * @returns The category's details.
+   * 
+   * @example
+   * sdk.admin.productCategory.update("pcat_123", {
+   *   name: "Shirts"
+   * })
+   * .then(({ product_category }) => {
+   *   console.log(product_category)
+   * })
+   */
   async update(
     id: string,
     body: HttpTypes.AdminUpdateProductCategory,
@@ -47,6 +84,52 @@ export class ProductCategory {
     )
   }
 
+  /**
+   * This method retrieves a paginated list of product categories. It sends a request to the 
+   * [List Product Categories](https://docs.medusajs.com/api/admin#product-categories_getproductcategories) API route.
+   * 
+   * @param query - Filters and pagination configurations.
+   * @param headers - Headers to pass in the request.
+   * @returns The paginated list of product categories.
+   * 
+   * @example
+   * To retrieve the list of product categories:
+   * 
+   * ```ts
+   * sdk.admin.productCategory.list()
+   * .then(({ product_categories, count, limit, offset }) => {
+   *   console.log(product_categories)
+   * })
+   * ```
+   * 
+   * 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.productCategory.list({
+   *   limit: 10,
+   *   offset: 10
+   * })
+   * .then(({ product_categories, count, limit, offset }) => {
+   *   console.log(product_categories)
+   * })
+   * ```
+   * 
+   * Using the `fields` query parameter, you can specify the fields and relations to retrieve
+   * in each product category:
+   * 
+   * ```ts
+   * sdk.admin.productCategory.list({
+   *   fields: "id,*products"
+   * })
+   * .then(({ product_categories, count, limit, offset }) => {
+   *   console.log(product_categories)
+   * })
+   * ```
+   * 
+   * Learn more about the `fields` property in the [API reference](https://docs.medusajs.com/api/store#select-fields-and-relations).
+   */
   async list(
     query?: HttpTypes.AdminProductCategoryListParams,
     headers?: ClientHeaders
@@ -60,6 +143,38 @@ export class ProductCategory {
     )
   }
 
+  /**
+   * This method retrieves a product category by its ID. It sends a request to the 
+   * [Get Product Category](https://docs.medusajs.com/api/admin#product-categories_getproductcategoriesid) API route.
+   * 
+   * @param id - The category's ID.
+   * @param query - Configure the fields to retrieve in the product category.
+   * @param headers - Headers to pass in the request
+   * @returns The product category's details.
+   * 
+   * @example
+   * To retrieve a product category by its ID:
+   * 
+   * ```ts
+   * sdk.admin.productCategory.retrieve("pcat_123")
+   * .then(({ product_category }) => {
+   *   console.log(product_category)
+   * })
+   * ```
+   * 
+   * To specify the fields and relations to retrieve:
+   * 
+   * ```ts
+   * sdk.admin.productCategory.retrieve("pcat_123", {
+   *   fields: "id,*products"
+   * })
+   * .then(({ product_category }) => {
+   *   console.log(product_category)
+   * })
+   * ```
+   * 
+   * 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.AdminProductCategoryParams,
@@ -74,6 +189,21 @@ export class ProductCategory {
     )
   }
 
+  /**
+   * This method deletes a product category. It sends a request to the
+   * [Delete Product Category](https://docs.medusajs.com/api/admin#product-categories_deleteproductcategoriesid)
+   * API route.
+   * 
+   * @param id - The category's ID.
+   * @param headers - Headers to pass in the request
+   * @returns The deletion's details.
+   * 
+   * @example
+   * sdk.admin.productCategory.delete("pcat_123")
+   * .then(({ deleted }) => {
+   *   console.log(deleted)
+   * })
+   */
   async delete(id: string, headers?: ClientHeaders) {
     return this.client.fetch<HttpTypes.AdminProductCategoryDeleteResponse>(
       `/admin/product-categories/${id}`,
@@ -84,6 +214,26 @@ export class ProductCategory {
     )
   }
 
+  /**
+   * This method manaes the products of a category to add or remove them. It sends a request
+   * to the [Manage Products](https://docs.medusajs.com/api/admin#product-categories_postproductcategoriesidproducts)
+   * API route.
+   * 
+   * @param id - The category's ID.
+   * @param body - The products to create or update.
+   * @param query - Configure the fields to retrieve in the product category.
+   * @param headers - Headers to pass in the request
+   * @returns The product category's details.
+   * 
+   * @example
+   * sdk.admin.productCategory.updateProducts("pcat_123", {
+   *   add: ["prod_123"],
+   *   remove: ["prod_321"]
+   * })
+   * .then(({ product_category }) => {
+   *   console.log(product_category)
+   * })
+   */
   async updateProducts(
     id: string,
     body: HttpTypes.AdminUpdateProductCategoryProducts,

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

@@ -14,6 +14,24 @@ export class ProductCollection {
     this.client = client
   }
 
+  /**
+   * This method creates a product collection. It sends a request to the 
+   * [Create Collection](https://docs.medusajs.com/api/admin#collections_postcollections)
+   * API route.
+   * 
+   * @param body - The details of the product collection to create.
+   * @param query - Configure the fields to retrieve in the product collection.
+   * @param headers - Headers to pass in the request
+   * @returns The product collection's details.
+   * 
+   * @example
+   * sdk.admin.productCollection.create({
+   *   title: "Summer Collection"
+   * })
+   * .then(({ collection }) => {
+   *   console.log(collection)
+   * })
+   */
   async create(
     body: HttpTypes.AdminCreateCollection,
     query?: HttpTypes.AdminCollectionParams,
@@ -29,6 +47,26 @@ export class ProductCollection {
       }
     )
   }
+
+  /**
+   * This method updates a collection. It sends a request to the
+   * [Update Collection](https://docs.medusajs.com/api/admin#collections_postcollectionsid)
+   * API route.
+   * 
+   * @param id - The ID of the collection.
+   * @param body - The data to update in the collection.
+   * @param query - Configure the fields to retrieve in the product collection.
+   * @param headers - Headers to pass in the request
+   * @returns The product collection's details.
+   * 
+   * @example
+   * sdk.admin.productCollection.update("pcol_123", {
+   *   title: "Summer Collection"
+   * })
+   * .then(({ collection }) => {
+   *   console.log(collection)
+   * })
+   */
   async update(
     id: string,
     body: HttpTypes.AdminUpdateCollection,
@@ -46,6 +84,52 @@ export class ProductCollection {
     )
   }
 
+  /**
+   * This method retrieves a paginated list of collections. It sends a request to the 
+   * [List Collections](https://docs.medusajs.com/api/admin#collections_getcollections) API route.
+   * 
+   * @param query - Filters and pagination configurations.
+   * @param headers - Headers to pass in the request.
+   * @returns The paginated list of collections.
+   * 
+   * @example
+   * To retrieve the list of collections:
+   * 
+   * ```ts
+   * sdk.admin.productCollection.list()
+   * .then(({ collections, count, limit, offset }) => {
+   *   console.log(collections)
+   * })
+   * ```
+   * 
+   * 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.productCollection.list({
+   *   limit: 10,
+   *   offset: 10
+   * })
+   * .then(({ collections, count, limit, offset }) => {
+   *   console.log(collections)
+   * })
+   * ```
+   * 
+   * Using the `fields` query parameter, you can specify the fields and relations to retrieve
+   * in each collection:
+   * 
+   * ```ts
+   * sdk.admin.productCollection.list({
+   *   fields: "id,*products"
+   * })
+   * .then(({ collections, count, limit, offset }) => {
+   *   console.log(collections)
+   * })
+   * ```
+   * 
+   * Learn more about the `fields` property in the [API reference](https://docs.medusajs.com/api/store#select-fields-and-relations).
+   */
   async list(
     queryParams?: HttpTypes.AdminCollectionListParams,
     headers?: ClientHeaders
@@ -59,6 +143,38 @@ export class ProductCollection {
     )
   }
 
+  /**
+   * This method retrieves a collection by its ID. It sends a request to the 
+   * [Get Collection](https://docs.medusajs.com/api/admin#collections_getcollectionsid) API route.
+   * 
+   * @param id - The collection's ID.
+   * @param query - Configure the fields to retrieve in the collection.
+   * @param headers - Headers to pass in the request
+   * @returns The collection's details.
+   * 
+   * @example
+   * To retrieve a collection by its ID:
+   * 
+   * ```ts
+   * sdk.admin.productCollection.retrieve("pcol_123")
+   * .then(({ collection }) => {
+   *   console.log(collection)
+   * })
+   * ```
+   * 
+   * To specify the fields and relations to retrieve:
+   * 
+   * ```ts
+   * sdk.admin.productCollection.retrieve("pcol_123", {
+   *   fields: "id,*products"
+   * })
+   * .then(({ collection }) => {
+   *   console.log(collection)
+   * })
+   * ```
+   * 
+   * 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.AdminCollectionParams,
@@ -73,6 +189,21 @@ export class ProductCollection {
     )
   }
 
+  /**
+   * This method deletes a product collection. It sends a request to the
+   * [Delete Collection](https://docs.medusajs.com/api/admin#collections_deletecollectionsid)
+   * API route.
+   * 
+   * @param id - The collection's ID.
+   * @param headers - Headers to pass in the request
+   * @returns The deletion's details.
+   * 
+   * @example
+   * sdk.admin.productCollection.delete("pcol_123")
+   * .then(({ deleted }) => {
+   *   console.log(deleted)
+   * })
+   */
   async delete(id: string, headers?: ClientHeaders) {
     return this.client.fetch<HttpTypes.AdminCollectionDeleteResponse>(
       `/admin/collections/${id}`,
@@ -83,6 +214,25 @@ export class ProductCollection {
     )
   }
 
+  /**
+   * This method manages the products of a collection to add or remove them. It sends a request
+   * to the [Manage Products](https://docs.medusajs.com/api/admin#collections_postcollectionsidproducts)
+   * API route.
+   * 
+   * @param id - The collection's ID.
+   * @param body - The products to add or remove.
+   * @param headers - Headers to pass in the request
+   * @returns The product category's details.
+   * 
+   * @example
+   * sdk.admin.productCollection.updateProducts("pcol_123", {
+   *   add: ["prod_123"],
+   *   remove: ["prod_321"]
+   * })
+   * .then(({ collection }) => {
+   *   console.log(collection)
+   * })
+   */
   async updateProducts(
     id: string,
     body: HttpTypes.AdminUpdateCollectionProducts,

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

@@ -1,16 +1,40 @@
 export interface AdminCreateCollection {
+  /**
+   * The collection's title.
+   */
   title: string
+  /**
+   * The collection's handle.
+   */
   handle?: string
+  /**
+   * Key-value pairs of custom data.
+   */
   metadata?: Record<string, any>
 }
 
 export interface AdminUpdateCollection {
+  /**
+   * The collection's title.
+   */
   title?: string
+  /**
+   * The collection's handle.
+   */
   handle?: string
+  /**
+   * Key-value pairs of custom data.
+   */
   metadata?: Record<string, any>
 }
 
 export interface AdminUpdateCollectionProducts {
+  /**
+   * IDs of products to add to the collection.
+   */
   add?: string[]
+  /**
+   * IDs of products to remove from the collection.
+   */
   remove?: string[]
 }

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

@@ -2,6 +2,9 @@ import { OperatorMap } from "../../../dal"
 import { BaseCollectionListParams, BaseCollectionParams } from "../common"
 
 export interface AdminCollectionListParams extends BaseCollectionListParams {
+  /**
+   * Apply filters on the collection's deletion date.
+   */
   deleted_at?: OperatorMap<string>
 }
 export interface AdminCollectionParams extends BaseCollectionParams {}

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

@@ -2,11 +2,17 @@ import { DeleteResponse, PaginatedResponse } from "../../common"
 import { AdminCollection } from "./entities"
 
 export interface AdminCollectionResponse {
+  /**
+   * The collection's details.
+   */
   collection: AdminCollection
 }
 
 export interface AdminCollectionListResponse
   extends PaginatedResponse<{
+    /**
+     * The list of collections.
+     */
     collections: AdminCollection[]
   }> {}
 

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

@@ -1,6 +1,6 @@
 export interface SelectParams {
   /**
-   * The fields and relations to retrieve.
+   * The fields and relations to retrieve separated by commas.
    * 
    * Learn more in the [API reference](https://docs.medusajs.com/api/store#select-fields-and-relations).
    */

packages/core/types/src/http/price-list/admin/entities.ts

@@ -2,21 +2,63 @@ import { PriceListStatus, PriceListType } from "../../../pricing"
 import { AdminPrice } from "../../pricing"
 
 export interface AdminPriceListPrice extends AdminPrice {
+  /**
+   * The ID of the variant that this price is for.
+   */
   variant_id: string
+  /**
+   * The price's rules.
+   */
   rules: Record<string, unknown>
 }
 
 export interface AdminPriceList {
+  /**
+   * The price list's ID.
+   */
   id: string
+  /**
+   * The price list's title.
+   */
   title: string
+  /**
+   * The price list's description.
+   */
   description: string
+  /**
+   * The price list's rules.
+   */
   rules: Record<string, any>
+  /**
+   * The price list's start date.
+   */
   starts_at: string | null
+  /**
+   * The price list's end date.
+   */
   ends_at: string | null
+  /**
+   * The price list's status.
+   */
   status: PriceListStatus
+  /**
+   * The price list's type.
+   */
   type: PriceListType
+  /**
+   * The price list's prices.
+   */
   prices: AdminPriceListPrice[]
+  /**
+   * The date the price list was created.
+   */
   created_at: string
+  /**
+   * The date the price list was updated.
+   */
   updated_at: string
+  /**
+   * The date the price list was deleted.
+   */
   deleted_at: string | null
 }

packages/core/types/src/http/price-list/admin/payloads.ts

@@ -1,51 +1,153 @@
 import { PriceListStatus, PriceListType } from "../../../pricing"
 
 export interface AdminCreatePriceListPrice {
+  /**
+   * The price's currency code.
+   * 
+   * @example
+   * usd
+   */
   currency_code: string
+  /**
+   * The price's amount.
+   */
   amount: number
+  /**
+   * The ID of the variant this price applies to.
+   */
   variant_id: string
+  /**
+   * The minimum quantity that must be available in the cart for the price to be applied.
+   */
   min_quantity?: number | null
+  /**
+   * The maximum quantity allowed to be available in the cart for the price to be applied.
+   */
   max_quantity?: number | null
+  /**
+   * The price's rules.
+   */
   rules?: Record<string, string>
 }
 
 export interface AdminCreatePriceList {
+  /**
+   * The price list's title.
+   */
   title: string
+  /**
+   * The price list's description.
+   */
   description?: string | null
+  /**
+   * The price list's start date.
+   */
   starts_at?: string | null
+  /**
+   * The price list's end date.
+   */
   ends_at?: string | null
+  /**
+   * The price list's status.
+   */
   status: PriceListStatus
+  /**
+   * The price list's type.
+   */
   type: PriceListType
+  /**
+   * The price list's rules.
+   */
   rules?: Record<string, string[]>
+  /**
+   * The price list's prices.
+   */
   prices?: AdminCreatePriceListPrice[]
 }
 
 export interface AdminUpdatePriceListPrice {
+  /**
+   * The ID of the price to update.
+   */
   id: string
+  /**
+   * The price's currency code.
+   * 
+   * @example
+   * usd
+   */
   currency_code?: string
+  /**
+   * The price's amount.
+   */
   amount?: number
+  /**
+   * The ID of the variant this price applies to.
+   */
   variant_id: string
+  /**
+   * The minimum quantity that must be available in the cart for the price to be applied.
+   */
   min_quantity?: number | null
+  /**
+   * The maximum quantity allowed to be available in the cart for the price to be applied.
+   */
   max_quantity?: number | null
+  /**
+   * The price's rules.
+   */
   rules?: Record<string, string>
 }
 
 export interface AdminUpdatePriceList {
+  /**
+   * The price list's title.
+   */
   title?: string
+  /**
+   * The price list's description.
+   */
   description?: string
+  /**
+   * The price list's start date.
+   */
   starts_at?: string | null
+  /**
+   * The price list's end date.
+   */
   ends_at?: string | null
+  /**
+   * The price list's status.
+   */
   status?: PriceListStatus
+  /**
+   * The price list's type.
+   */
   type?: PriceListType
+  /**
+   * The price list's rules.
+   */
   rules?: Record<string, string[]>
 }
 
 export interface AdminBatchPriceListPrice {
+  /**
+   * The prices to create and add to the price list.
+   */
   create?: AdminCreatePriceListPrice[]
+  /**
+   * The prices to update in the price list.
+   */
   update?: AdminUpdatePriceListPrice[]
+  /**
+   * The prices to delete from the price list.
+   */
   delete?: string[]
 }
 
 export interface AdminLinkPriceListProducts {
+  /**
+   * The IDs of products to remove from the price list.
+   */
   remove?: string[]
 }

packages/core/types/src/http/price-list/admin/queries.ts

@@ -5,11 +5,29 @@ import { FindParams, SelectParams } from "../../common"
 export interface AdminPriceListListParams
   extends FindParams,
     BaseFilterable<AdminPriceListListParams> {
+  /**
+   * Query or keyword to filter the price list's searchable fields.
+   */
   q?: string
+  /**
+   * Filter by price list ID(s).
+   */
   id?: string | string[]
+  /**
+   * Apply filters on the price list's start date.
+   */
   starts_at?: OperatorMap<string>
+  /**
+   * Apply filters on the price list's end date.
+   */
   ends_at?: OperatorMap<string>
+  /**
+   * Filter by statuses.
+   */
   status?: PriceListStatus[]
+  /**
+   * Filter by the number of rules.
+   */
   rules_count?: number[]
 }
 

packages/core/types/src/http/price-list/admin/responses.ts

@@ -3,11 +3,17 @@ import { AdminPrice } from "../../pricing"
 import { AdminPriceList } from "./entities"
 
 export interface AdminPriceListResponse {
+  /**
+   * The price list's details.
+   */
   price_list: AdminPriceList
 }
 
 export interface AdminPriceListListResponse
   extends PaginatedResponse<{
+    /**
+     * The list of price lists.
+     */
     price_lists: AdminPriceList[]
   }> {}
 
@@ -15,8 +21,17 @@ export interface AdminPriceListDeleteResponse
   extends DeleteResponse<"price_list"> {}
 
 export interface AdminPriceListBatchResponse {
+  /**
+   * The created prices.
+   */
   created: AdminPrice[]
+  /**
+   * The updated prices.
+   */
   updated: AdminPrice[]
+  /**
+   * Details about the deleted prices.
+   */
   deleted: {
     ids: string[]
     object: "price"

packages/core/types/src/http/pricing/admin/entities.ts

@@ -1,4 +1,5 @@
 /**
+ * @privateRemarks
  * TODO: Not sure how to type this properly, as it's unclear to me what is returned
  * by our API. As an example we return `price_list: null` but `price_list_id` is missing.
  *
@@ -17,25 +18,87 @@
  * ```
  */
 export interface AdminPrice {
+  /**
+   * The price's ID.
+   */
   id: string
+  /**
+   * The price's title.
+   */
   title: string
+  /**
+   * The price's currency code.
+   * 
+   * @example
+   * usd
+   */
   currency_code: string
+  /**
+   * The price's amount.
+   */
   amount: number
+  /**
+   * The price's raw amount.
+   */
   raw_amount: Record<string, unknown>
+  /**
+   * The minimum quantity that must be available in the cart for the price to be applied.
+   */
   min_quantity: number | null
+  /**
+   * The maximum quantity allowed to be available in the cart for the price to be applied.
+   */
   max_quantity: number | null
+  /**
+   * The ID of the price set this price belongs to.
+   */
   price_set_id: string
+  /**
+   * The date the price was created.
+   */
   created_at: string
+  /**
+   * The date the price was updated.
+   */
   updated_at: string
+  /**
+   * The date the price was deleted.
+   */
   deleted_at: string | null
 }
 
 export interface AdminPricePreference {
+  /**
+   * The price preference's ID.
+   */
   id: string
+  /**
+   * The attribute that the price preference refers to.
+   * 
+   * Current supported values: `region_id` and `currency_code`.
+   */
   attribute: string | null
+  /**
+   * The attribute's value. For example, if the `attribute` is `region_id`,
+   * the value is a region's ID. Prices in that region use this price
+   * preference.
+   */
   value: string | null
+  /**
+   * Whether prices matching this price preference have
+   * taxes included in their amount.
+   */
   is_tax_inclusive: boolean
+  /**
+   * The date that the price preference was created.
+   */
   created_at: string
+  /**
+   * The date that the price preference was updated.
+   */
   updated_at: string
+  /**
+   * The date that the price preference was deleted.
+   */
   deleted_at: null | string
 }

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

@@ -1,11 +1,39 @@
 export interface AdminCreatePricePreference {
+  /**
+   * The attribute that the price preference refers to.
+   * 
+   * Current supported values: `region_id` and `currency_code`.
+   */
   attribute?: string
+  /**
+   * The attribute's value. For example, if the `attribute` is `region_id`,
+   * the value is a region's ID. Prices in that region use this price
+   * preference.
+   */
   value?: string
+  /**
+   * Whether prices matching this price preference have
+   * taxes included in their amount.
+   */
   is_tax_inclusive?: boolean
 }
 
 export interface AdminUpdatePricePreference {
+  /**
+   * The attribute that the price preference refers to.
+   * 
+   * Current supported values: `region_id` and `currency_code`.
+   */
   attribute?: string | null
+  /**
+   * The attribute's value. For example, if the `attribute` is `region_id`,
+   * the value is a region's ID. Prices in that region use this price
+   * preference.
+   */
   value?: string | null
+  /**
+   * Whether prices matching this price preference have
+   * taxes included in their amount.
+   */
   is_tax_inclusive?: boolean
 }

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

@@ -4,9 +4,21 @@ import { FindParams, SelectParams } from "../../common"
 export interface AdminPricePreferenceListParams
   extends FindParams,
     BaseFilterable<AdminPricePreferenceListParams> {
+  /**
+   * Filter by price preference ID(s).
+   */
   id?: string | string[]
+  /**
+   * Filter by attribute(s).
+   */
   attribute?: string | string[]
+  /**
+   * Filter by value(s).
+   */
   value?: string | string[]
+  /**
+   * Query or keyword to filter the price preference's searchable fields.
+   */
   q?: string
 }
 

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

@@ -2,11 +2,17 @@ import { DeleteResponse, PaginatedResponse } from "../../common"
 import { AdminPricePreference } from "./entities"
 
 export interface AdminPricePreferenceResponse {
+  /**
+   * The price preference's details.
+   */
   price_preference: AdminPricePreference
 }
 
 export interface AdminPricePreferenceListResponse
   extends PaginatedResponse<{
+    /**
+     * The list of price preferences.
+     */
     price_preferences: AdminPricePreference[]
   }> {}
 

packages/core/types/src/http/product-category/admin/entities.ts

@@ -6,7 +6,16 @@ export interface AdminProductCategory
     BaseProductCategory,
     "products" | "category_children" | "parent_category"
   > {
+  /**
+   * The category's children.
+   */
   category_children: AdminProductCategory[]
+  /**
+   * The parent category's details.
+   */
   parent_category: AdminProductCategory | null
+  /**
+   * The products that belong to this category.
+   */
   products?: AdminProduct[]
 }

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

@@ -1,26 +1,86 @@
 export interface AdminCreateProductCategory {
+  /**
+   * The product category's name.
+   */
   name: string
+  /**
+   * The product category's description.
+   */
   description?: string
+  /**
+   * The product category's unique handle. Can be used to create
+   * human-readable URLs.
+   */
   handle?: string
+  /**
+   * Whether the category is only available and viewable by
+   * admin users.
+   */
   is_internal?: boolean
+  /**
+   * Whether the category is active. If disabled, the category
+   * isn't retrieved in the store API routes.
+   */
   is_active?: boolean
+  /**
+   * The ID of the parent category.
+   */
   parent_category_id?: string
+  /**
+   * The category's ranking among its sibling categories.
+   */
   rank?: number
+  /**
+   * Key-value pairs of custom data.
+   */
   metadata?: Record<string, unknown>
 }
 
 export interface AdminUpdateProductCategory {
+  /**
+   * The product category's name.
+   */
   name?: string
+  /**
+   * The product category's description.
+   */
   description?: string
+  /**
+   * The product category's unique handle. Can be used to create
+   * human-readable URLs.
+   */
   handle?: string
+  /**
+   * Whether the category is only available and viewable by
+   * admin users.
+   */
   is_internal?: boolean
+  /**
+   * Whether the category is active. If disabled, the category
+   * isn't retrieved in the store API routes.
+   */
   is_active?: boolean
+  /**
+   * The ID of the parent category.
+   */
   parent_category_id?: string | null
+  /**
+   * The category's ranking among its sibling categories.
+   */
   rank?: number
+  /**
+   * Key-value pairs of custom data.
+   */
   metadata?: Record<string, unknown>
 }
 
 export interface AdminUpdateProductCategoryProducts {
+  /**
+   * IDs of products to add to the category.
+   */
   add?: string[]
+  /**
+   * IDs of products to remove from the category.
+   */
   remove?: string[]
 }

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

@@ -5,7 +5,13 @@ import {
 
 export interface AdminProductCategoryListParams
   extends BaseProductCategoryListParams {
+  /**
+   * Filter by whether the category is only available internally.
+   */
   is_internal?: boolean
+  /**
+   * Filter by whether the category is active.
+   */
   is_active?: boolean
 }
 

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

@@ -2,11 +2,17 @@ import { DeleteResponse, PaginatedResponse } from "../../common"
 import { AdminProductCategory } from "./entities"
 
 export interface AdminProductCategoryResponse {
+  /**
+   * The category's details.
+   */
   product_category: AdminProductCategory
 }
 
 export interface AdminProductCategoryListResponse
   extends PaginatedResponse<{
+    /**
+     * The list of product categories.
+     */
     product_categories: AdminProductCategory[]
   }> {}
 

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

@@ -16,7 +16,8 @@ export interface BaseProductCategory {
    */
   description: string
   /**
-   * The category's handle.
+   * The product category's unique handle. Can be used to create
+   * human-readable URLs.
    */
   handle: string
   /**