chore(core-flows,types): improve TSDocs of inventory-related workflows (

#11013)

packages/core/core-flows/src/inventory/steps/adjust-inventory-levels.ts

@@ -3,14 +3,30 @@ import { StepResponse, createStep } from "@medusajs/framework/workflows-sdk"
 
 import { MathBN, Modules } from "@medusajs/framework/utils"
 
+/**
+ * The data to adjust the inventory levels.
+ */
+export type AdjustInventoryLevelsStepInput = InventoryTypes.BulkAdjustInventoryLevelInput[]
+
 export const adjustInventoryLevelsStepId = "adjust-inventory-levels-step"
 /**
- * This step adjusts one or more inventory levels.
+ * This step adjusts the stocked quantity of one or more inventory levels. You can 
+ * pass a positive value in `adjustment` to add to the stocked quantity, or a negative value to
+ * subtract from the stocked quantity.
+ * 
+ * @example
+ * const data = adjustInventoryLevelsStep([
+ *   {
+ *     inventory_item_id: "iitem_123",
+ *     location_id: "sloc_123",
+ *     adjustment: 10,
+ *   }
+ * ])
  */
 export const adjustInventoryLevelsStep = createStep(
   adjustInventoryLevelsStepId,
   async (
-    input: InventoryTypes.BulkAdjustInventoryLevelInput[],
+    input: AdjustInventoryLevelsStepInput,
     { container }
   ) => {
     const inventoryService: IInventoryService = container.resolve(

packages/core/core-flows/src/inventory/steps/attach-inventory-items.ts

@@ -2,18 +2,37 @@ import { createStep, StepResponse } from "@medusajs/framework/workflows-sdk"
 
 import { ContainerRegistrationKeys, Modules } from "@medusajs/framework/utils"
 
+/**
+ * The data to attach inventory items to variants.
+ */
+export type AttachInventoryItemToVariantsStepInput = {
+  /**
+   * The inventory item ID to attach to the variant.
+   */
+  inventoryItemId: string
+  /**
+   * The variant ID to attach the inventory item to.
+   */
+  tag: string
+}[]
+
 export const attachInventoryItemToVariantsStepId =
   "attach-inventory-items-to-variants-step"
 /**
  * This step creates one or more links between variant and inventory item records.
+ * 
+ * @example
+ * const data = attachInventoryItemToVariants([
+ *   {
+ *     inventoryItemId: "iitem_123",
+ *     tag: "variant_123"
+ *   }
+ * ])
  */
 export const attachInventoryItemToVariants = createStep(
   attachInventoryItemToVariantsStepId,
   async (
-    input: {
-      inventoryItemId: string
-      tag?: string
-    }[],
+    input: AttachInventoryItemToVariantsStepInput,
     { container }
   ) => {
     const remoteLink = container.resolve(ContainerRegistrationKeys.LINK)

packages/core/core-flows/src/inventory/steps/create-inventory-items.ts

@@ -3,13 +3,18 @@ import { StepResponse, createStep } from "@medusajs/framework/workflows-sdk"
 import { IInventoryService, InventoryTypes } from "@medusajs/framework/types"
 import { Modules } from "@medusajs/framework/utils"
 
+/**
+ * The data to create the inventory items.
+ */
+export type CreateInventoryItemsStepInput = InventoryTypes.CreateInventoryItemInput[]
+
 export const createInventoryItemsStepId = "create-inventory-items"
 /**
  * This step creates one or more inventory items.
  */
 export const createInventoryItemsStep = createStep(
   createInventoryItemsStepId,
-  async (data: InventoryTypes.CreateInventoryItemInput[], { container }) => {
+  async (data: CreateInventoryItemsStepInput, { container }) => {
     const inventoryService: IInventoryService = container.resolve(
       Modules.INVENTORY
     )

packages/core/core-flows/src/inventory/steps/create-inventory-levels.ts

@@ -3,13 +3,18 @@ import { StepResponse, createStep } from "@medusajs/framework/workflows-sdk"
 
 import { Modules } from "@medusajs/framework/utils"
 
+/**
+ * The data to create the inventory levels.
+ */
+export type CreateInventoryLevelsStepInput = InventoryTypes.CreateInventoryLevelInput[]
+
 export const createInventoryLevelsStepId = "create-inventory-levels"
 /**
  * This step creates one or more inventory levels.
  */
 export const createInventoryLevelsStep = createStep(
   createInventoryLevelsStepId,
-  async (data: InventoryTypes.CreateInventoryLevelInput[], { container }) => {
+  async (data: CreateInventoryLevelsStepInput, { container }) => {
     const service = container.resolve<IInventoryService>(Modules.INVENTORY)
     const inventoryLevels = await service.createInventoryLevels(data)
     return new StepResponse(

packages/core/core-flows/src/inventory/steps/delete-inventory-items.ts

@@ -26,13 +26,18 @@ export const validateInventoryDeleteStep = createStep(
   }
 )
 
+/**
+ * The IDs of the inventory items to delete.
+ */
+export type DeleteInventoryItemStepInput = string[]
+
 export const deleteInventoryItemStepId = "delete-inventory-item-step"
 /**
  * This step deletes one or more inventory items.
  */
 export const deleteInventoryItemStep = createStep(
   deleteInventoryItemStepId,
-  async (ids: string[], { container }) => {
+  async (ids: DeleteInventoryItemStepInput, { container }) => {
     const inventoryService = container.resolve(Modules.INVENTORY)
 
     await inventoryService.softDeleteInventoryItems(ids)

packages/core/core-flows/src/inventory/steps/delete-inventory-levels.ts

@@ -3,13 +3,18 @@ import { StepResponse, createStep } from "@medusajs/framework/workflows-sdk"
 
 import { Modules } from "@medusajs/framework/utils"
 
+/**
+ * The IDs of inventory levels to delete.
+ */
+export type DeleteInventoryLevelsStepInput = string[]
+
 export const deleteInventoryLevelsStepId = "delete-inventory-levels-step"
 /**
  * This step deletes one or more inventory levels.
  */
 export const deleteInventoryLevelsStep = createStep(
   deleteInventoryLevelsStepId,
-  async (ids: string[], { container }) => {
+  async (ids: DeleteInventoryLevelsStepInput, { container }) => {
     const service = container.resolve<IInventoryService>(Modules.INVENTORY)
 
     await service.softDeleteInventoryLevels(ids)

packages/core/core-flows/src/inventory/steps/update-inventory-items.ts

@@ -7,13 +7,18 @@ import { StepResponse, createStep } from "@medusajs/framework/workflows-sdk"
 
 import { Modules } from "@medusajs/framework/utils"
 
+/**
+ * The data to update the inventory items.
+ */
+export type UpdateInventoryItemsStepInput = InventoryTypes.UpdateInventoryItemInput[]
+
 export const updateInventoryItemsStepId = "update-inventory-items-step"
 /**
  * This step updates one or more inventory items.
  */
 export const updateInventoryItemsStep = createStep(
   updateInventoryItemsStepId,
-  async (input: InventoryTypes.UpdateInventoryItemInput[], { container }) => {
+  async (input: UpdateInventoryItemsStepInput, { container }) => {
     const inventoryService = container.resolve<IInventoryService>(
       Modules.INVENTORY
     )

packages/core/core-flows/src/inventory/steps/update-inventory-levels.ts

@@ -7,13 +7,18 @@ import { StepResponse, createStep } from "@medusajs/framework/workflows-sdk"
 
 import { Modules } from "@medusajs/framework/utils"
 
+/**
+ * The data to update the inventory levels.
+ */
+export type UpdateInventoryLevelsStepInput = InventoryTypes.UpdateInventoryLevelInput[]
+
 export const updateInventoryLevelsStepId = "update-inventory-levels-step"
 /**
  * This step updates one or more inventory levels.
  */
 export const updateInventoryLevelsStep = createStep(
   updateInventoryLevelsStepId,
-  async (input: InventoryTypes.UpdateInventoryLevelInput[], { container }) => {
+  async (input: UpdateInventoryLevelsStepInput, { container }) => {
     const inventoryService: IInventoryService = container.resolve(
       Modules.INVENTORY
     )

packages/core/core-flows/src/inventory/steps/validate-inventory-items.ts

@@ -5,13 +5,19 @@ import {
 } from "@medusajs/framework/utils"
 import { createStep } from "@medusajs/framework/workflows-sdk"
 
+/**
+ * The IDs of the inventory items to validate.
+ */
+export type ValidateInventoryItemsStepInput = string[]
+
 export const validateInventoryItemsId = "validate-inventory-items-step"
 /**
  * This step ensures that the inventory items with the specified IDs exist.
+ * If not valid, the step will throw an error.
  */
 export const validateInventoryItems = createStep(
   validateInventoryItemsId,
-  async (id: string[], { container }) => {
+  async (id: ValidateInventoryItemsStepInput, { container }) => {
     const remoteQuery = container.resolve(
       ContainerRegistrationKeys.REMOTE_QUERY
     )

packages/core/core-flows/src/inventory/steps/validate-inventory-locations.ts

@@ -7,13 +7,20 @@ import {
 import { InventoryTypes } from "@medusajs/framework/types"
 import { createStep } from "@medusajs/framework/workflows-sdk"
 
+/**
+ * The data to validate the inventory levels.
+ */
+export type ValidateInventoryLocationsStepInput = InventoryTypes.CreateInventoryLevelInput[]
+
 export const validateInventoryLocationsStepId = "validate-inventory-levels-step"
 /**
- * This step ensures that the inventory levels exist for each specified pair of inventory item and location.
+ * This step ensures that the inventory levels exist for each 
+ * specified pair of inventory item and location. If not,
+ * the step will throw an error.
  */
 export const validateInventoryLocationsStep = createStep(
   validateInventoryLocationsStepId,
-  async (data: InventoryTypes.CreateInventoryLevelInput[], { container }) => {
+  async (data: ValidateInventoryLocationsStepInput, { container }) => {
     const remoteQuery = container.resolve(
       ContainerRegistrationKeys.REMOTE_QUERY
     )

packages/core/core-flows/src/inventory/steps/validate-singular-inventory-items-for-tags.ts

@@ -5,17 +5,33 @@ import {
 } from "@medusajs/framework/utils"
 import { createStep, StepResponse } from "@medusajs/framework/workflows-sdk"
 
+/**
+ * The data to validate inventory items for creation.
+ */
+export type ValidateInventoryItemsForCreateStepInput = {
+  /**
+   * The ID of the variant to validate.
+   */
+  tag?: string
+}[]
+
 export const validateInventoryItemsForCreateStepId =
   "validate-inventory-items-for-create-step"
 /**
  * This step checks whether a variant already has an inventory item.
+ * If so, the step will throw an error.
+ * 
+ * @example
+ * const data = validateInventoryItemsForCreate([
+ *   {
+ *     tag: "variant_123"
+ *   }
+ * ])
  */
 export const validateInventoryItemsForCreate = createStep(
   validateInventoryItemsForCreateStepId,
   async (
-    input: {
-      tag?: string
-    }[],
+    input: ValidateInventoryItemsForCreateStepInput,
     { container }
   ) => {
     const remoteLink = container.resolve(ContainerRegistrationKeys.LINK)

packages/core/core-flows/src/inventory/workflows/batch-inventory-item-levels.ts

@@ -5,18 +5,25 @@ import {
   WorkflowData,
   WorkflowResponse,
 } from "@medusajs/framework/workflows-sdk"
-import { BatchWorkflowInput, InventoryTypes } from "@medusajs/types"
+import { BatchWorkflowInput, BatchWorkflowOutput, InventoryLevelDTO, InventoryTypes } from "@medusajs/types"
 import { createInventoryLevelsStep, updateInventoryLevelsStep } from "../steps"
 import { deleteInventoryLevelsWorkflow } from "./delete-inventory-levels"
 
+/**
+ * The data to manage the inventory levels in bulk.
+ * 
+ * @property create - The inventory levels to create.
+ * @property update - The inventory levels to update.
+ * @property delete - The IDs of inventory levels to delete.
+ */
 export interface BatchInventoryItemLevelsWorkflowInput
   extends BatchWorkflowInput<
     InventoryTypes.CreateInventoryLevelInput,
     InventoryTypes.UpdateInventoryLevelInput
   > {
   /**
-   * If true, the workflow will force deletion of the inventory levels, even
-   * if they have a non-zero stocked quantity. It false, the workflow will
+   * If true, the workflow will force the deletion of the inventory levels, even
+   * if they have a non-zero stocked quantity. If false, the workflow will
    * not delete the inventory levels if they have a non-zero stocked quantity.
    *
    * Inventory levels that have reserved or incoming items at the location
@@ -27,9 +34,50 @@ export interface BatchInventoryItemLevelsWorkflowInput
   force?: boolean
 }
 
+/**
+ * The result of managing inventory levels in bulk.
+ * 
+ * @property created - The inventory levels that were created.
+ * @property updated - The inventory levels that were updated.
+ * @property deleted - The IDs of the inventory levels that were deleted.
+ */
+export type BatchInventoryItemLevelsWorkflowOutput = BatchWorkflowOutput<InventoryLevelDTO>
+
 export const batchInventoryItemLevelsWorkflowId =
   "batch-inventory-item-levels-workflow"
 
+/**
+ * This workflow creates, updates and deletes inventory levels in bulk.
+ * 
+ * You can use this workflow within your own customizations or custom workflows, allowing you
+ * to manage inventory levels in your custom flows.
+ * 
+ * @example
+ * const { result } = await batchInventoryItemLevelsWorkflow(container)
+ * .run({
+ *   input: {
+ *     create: [
+ *       {
+ *         inventory_item_id: "iitem_123",
+ *         location_id: "sloc_123"
+ *       }
+ *     ],
+ *     update: [
+ *       {
+ *         id: "iilev_123",
+ *         inventory_item_id: "iitem_123",
+ *         location_id: "sloc_123",
+ *         stocked_quantity: 10
+ *       }
+ *     ],
+ *     delete: ["iilev_321"]
+ *   }
+ * })
+ * 
+ * @summary
+ * 
+ * Manage inventory levels in bulk.
+ */
 export const batchInventoryItemLevelsWorkflow = createWorkflow(
   batchInventoryItemLevelsWorkflowId,
   (input: WorkflowData<BatchInventoryItemLevelsWorkflowInput>) => {
@@ -61,7 +109,7 @@ export const batchInventoryItemLevelsWorkflow = createWorkflow(
           created: data.res[0],
           updated: data.res[1],
           deleted: data.input.delete,
-        }
+        } as BatchInventoryItemLevelsWorkflowOutput
       })
     )
   }