chore(types): Add TSDoc comments to IInventoryService (#5630)

* chore(types): Add TSDoc comments to IInventoryService

* fix description of list methods

* address PR feedback

.changeset/long-carrots-tap.md

@@ -0,0 +1,5 @@
+---
+"@medusajs/types": patch
+---
+
+fix(types): Fix types used in the IInventoryService

packages/types/src/inventory/common.ts

@@ -202,8 +202,27 @@ export type InventoryLevelDTO = {
   deleted_at: string | Date | null
 }
 
+/**
+ * @interface
+ * 
+ * The filters to apply on retrieved reservation items.
+ * 
+ * @prop id - The IDs to filter reservation items by.
+ * @prop line_item_id - Filter reservation items by the ID of their associated line item.
+ * @prop inventory_item_id - Filter reservation items by the ID of their associated inventory item.
+ * @prop location_id - Filter reservation items by the ID of their associated location.
+ * @prop description - Description filters to apply on the reservation items' `description` attribute.
+ * @prop created_by - The "created by" values to filter reservation items by.
+ * @prop quantity - Filters to apply on the reservation items' `quantity` attribute.
+ */
 export type FilterableReservationItemProps = {
   id?: string | string[]
+  /**
+   * @ignore
+   * 
+   * @privateRemark
+   * This property is not used.
+   */
   type?: string | string[]
   line_item_id?: string | string[]
   inventory_item_id?: string | string[]
@@ -213,6 +232,19 @@ export type FilterableReservationItemProps = {
   quantity?: number | NumericalComparisonOperator
 }
 
+/**
+ * @interface
+ * 
+ * The filters to apply on retrieved inventory items.
+ * 
+ * @prop id - The IDs to filter inventory items by.
+ * @prop location_id - Filter inventory items by the ID of their associated location.
+ * @prop q - Search term to search inventory items' attributes.
+ * @prop sku - The SKUs to filter inventory items by.
+ * @prop origin_country - The origin country to filter inventory items by.
+ * @prop hs_code - The HS Codes to filter inventory items by.
+ * @prop requires_shipping - Filter inventory items by whether they require shipping.
+ */
 export type FilterableInventoryItemProps = {
   id?: string | string[]
   location_id?: string | string[]
@@ -223,6 +255,26 @@ export type FilterableInventoryItemProps = {
   requires_shipping?: boolean
 }
 
+/**
+ * @interface
+ * 
+ * The details of the inventory item to be created.
+ * 
+ * @prop sku - The SKU of the inventory item.
+ * @prop origin_country - The origin country of the inventory item.
+ * @prop mid_code - The MID code of the inventory item.
+ * @prop material - The material of the inventory item.
+ * @prop weight - The weight of the inventory item.
+ * @prop length - The length of the inventory item.
+ * @prop height - The height of the inventory item.
+ * @prop width - The width of the inventory item.
+ * @prop title - The title of the inventory item.
+ * @prop description - The description of the inventory item.
+ * @prop thumbnail - The thumbnail of the inventory item.
+ * @prop metadata - Holds custom data in key-value pairs.
+ * @prop hs_code - The HS code of the inventory item.
+ * @prop requries_shipping - Whether the inventory item requires shipping.
+ */
 export type CreateInventoryItemInput = {
   sku?: string | null
   origin_country?: string | null
@@ -240,6 +292,20 @@ export type CreateInventoryItemInput = {
   requires_shipping?: boolean
 }
 
+/**
+ * @interface
+ * 
+ * The details of the reservation item to be created.
+ * 
+ * @prop line_item_id - The ID of the associated line item.
+ * @prop inventory_item_id - The ID of the associated inventory item.
+ * @prop location_id - The ID of the associated location.
+ * @prop quantity - The reserved quantity.
+ * @prop description - The description of the reservation.
+ * @prop created_by - The user or system that created the reservation. Can be any form of identification string.
+ * @prop external_id - An ID associated with an external third-party system that the reservation item is connected to.
+ * @prop metadata - Holds custom data in key-value pairs.
+ */
 export type CreateReservationItemInput = {
   line_item_id?: string
   inventory_item_id: string
@@ -251,6 +317,17 @@ export type CreateReservationItemInput = {
   metadata?: Record<string, unknown> | null
 }
 
+/**
+ * @interface
+ * 
+ * The filters to apply on retrieved inventory levels.
+ * 
+ * @prop inventory_item_id - Filter inventory levels by the ID of their associated inventory item.
+ * @prop location_id - Filter inventory levels by the ID of their associated inventory location.
+ * @prop stocked_quantity - Filters to apply on inventory levels' `stocked_quantity` attribute.
+ * @prop reserved_quantity - Filters to apply on inventory levels' `reserved_quantity` attribute.
+ * @prop incoming_quantity - Filters to apply on inventory levels' `incoming_quantity` attribute.
+ */
 export type FilterableInventoryLevelProps = {
   inventory_item_id?: string | string[]
   location_id?: string | string[]
@@ -259,6 +336,17 @@ export type FilterableInventoryLevelProps = {
   incoming_quantity?: number | NumericalComparisonOperator
 }
 
+/**
+ * @interface
+ * 
+ * The details of the inventory level to be created.
+ * 
+ * @prop inventory_item_id - The ID of the associated inventory item.
+ * @prop location_id - The ID of the associated location.
+ * @prop stocked_quantity - The stocked quantity of the associated inventory item in the associated location.
+ * @prop reserved_quantity - The reserved quantity of the associated inventory item in the associated location.
+ * @prop incoming_quantity - The incoming quantity of the associated inventory item in the associated location.
+ */
 export type CreateInventoryLevelInput = {
   inventory_item_id: string
   location_id: string
@@ -267,16 +355,42 @@ export type CreateInventoryLevelInput = {
   incoming_quantity?: number
 }
 
+/**
+ * @interface
+ * 
+ * The attributes to update in an inventory level.
+ * 
+ * @prop stocked_quantity - The stocked quantity of the associated inventory item in the associated location.
+ * @prop incoming_quantity - The incoming quantity of the associated inventory item in the associated location.
+ */
 export type UpdateInventoryLevelInput = {
   stocked_quantity?: number
   incoming_quantity?: number
 }
 
+/**
+ * @interface
+ * 
+ * The attributes to update in an inventory level. The inventory level is identified by the IDs of its associated inventory item and location.
+ * 
+ * @prop inventory_item_id - The ID of the associated inventory level.
+ * @prop location_id - The ID of the associated location.
+ */
 export type BulkUpdateInventoryLevelInput = {
   inventory_item_id: string
   location_id: string
 } & UpdateInventoryLevelInput
 
+/**
+ * @interface
+ * 
+ * The attributes to update in a reservation item.
+ * 
+ * @prop quantity - The reserved quantity.
+ * @prop location_id - The ID of the associated location.
+ * @prop description - The description of the reservation item.
+ * @prop metadata - Holds custom data in key-value pairs.
+ */
 export type UpdateReservationItemInput = {
   quantity?: number
   location_id?: string