chore(core-flows): [5] export types and types, add basic TSDocs (#8510)

This PR exports types and steps from the core-flows package, and adds simple TSDocs for workflows / steps. This is essential for the workflows reference.

PR 5/n

packages/core/core-flows/src/fulfillment/steps/add-shipping-options-prices.ts

@@ -6,23 +6,23 @@ import {
 import { ModuleRegistrationName } from "@medusajs/utils"
 import { createStep, StepResponse } from "@medusajs/workflows-sdk"
 
-interface PriceCurrencyCode {
+export interface ShippingOptionsPriceCurrencyCode {
   currency_code: string
   amount: number
 }
 
-interface PriceRegionId {
+interface ShippingOptionsPriceRegionId {
   region_id: string
   amount: number
 }
 
-type StepInput = {
+export type CreateShippingOptionsPriceSetsStepInput = {
   id: string
-  prices: (PriceCurrencyCode | PriceRegionId)[]
+  prices: (ShippingOptionsPriceCurrencyCode | ShippingOptionsPriceRegionId)[]
 }[]
 
 function buildPriceSet(
-  prices: StepInput[0]["prices"],
+  prices: CreateShippingOptionsPriceSetsStepInput[0]["prices"],
   regionToCurrencyMap: Map<string, string>
 ): CreatePriceSetDTO {
   const shippingOptionPrices = prices.map((price) => {
@@ -47,9 +47,12 @@ function buildPriceSet(
 
 export const createShippingOptionsPriceSetsStepId =
   "add-shipping-options-prices-step"
+/**
+ * This step creates price sets for one or more shipping options.
+ */
 export const createShippingOptionsPriceSetsStep = createStep(
   createShippingOptionsPriceSetsStepId,
-  async (data: StepInput, { container }) => {
+  async (data: CreateShippingOptionsPriceSetsStepInput, { container }) => {
     if (!data?.length) {
       return new StepResponse([], [])
     }
@@ -57,7 +60,7 @@ export const createShippingOptionsPriceSetsStep = createStep(
     const regionIds = data
       .map((input) => input.prices)
       .flat()
-      .filter((price): price is PriceRegionId => {
+      .filter((price): price is ShippingOptionsPriceRegionId => {
         return "region_id" in price
       })
       .map((price) => price.region_id)

packages/core/core-flows/src/fulfillment/steps/cancel-fulfillment.ts

@@ -3,6 +3,9 @@ import { ModuleRegistrationName } from "@medusajs/utils"
 import { StepResponse, createStep } from "@medusajs/workflows-sdk"
 
 export const cancelFulfillmentStepId = "cancel-fulfillment"
+/**
+ * This step cancels a fulfillment.
+ */
 export const cancelFulfillmentStep = createStep(
   cancelFulfillmentStepId,
   async (id: string, { container }) => {

packages/core/core-flows/src/fulfillment/steps/create-fulfillment-set.ts

@@ -6,6 +6,9 @@ import { ModuleRegistrationName } from "@medusajs/utils"
 import { StepResponse, createStep } from "@medusajs/workflows-sdk"
 
 export const createFulfillmentSetsId = "create-fulfillment-sets"
+/**
+ * This step creates one or more fulfillment sets.
+ */
 export const createFulfillmentSets = createStep(
   createFulfillmentSetsId,
   async (data: CreateFulfillmentSetDTO[], { container }) => {

packages/core/core-flows/src/fulfillment/steps/create-fulfillment.ts

@@ -3,6 +3,9 @@ import { ModuleRegistrationName } from "@medusajs/utils"
 import { StepResponse, createStep } from "@medusajs/workflows-sdk"
 
 export const createFulfillmentStepId = "create-fulfillment"
+/**
+ * This step creates a fulfillment
+ */
 export const createFulfillmentStep = createStep(
   createFulfillmentStepId,
   async (data: FulfillmentTypes.CreateFulfillmentDTO, { container }) => {

packages/core/core-flows/src/fulfillment/steps/create-return-fulfillment.ts

@@ -3,6 +3,9 @@ import { ModuleRegistrationName } from "@medusajs/utils"
 import { StepResponse, createStep } from "@medusajs/workflows-sdk"
 
 export const createReturnFulfillmentStepId = "create-return-fulfillment"
+/**
+ * This step creates a fulfillment for a return.
+ */
 export const createReturnFulfillmentStep = createStep(
   createReturnFulfillmentStepId,
   async (data: FulfillmentTypes.CreateFulfillmentDTO, { container }) => {

packages/core/core-flows/src/fulfillment/steps/create-service-zones.ts

@@ -5,12 +5,13 @@ import {
 import { ModuleRegistrationName } from "@medusajs/utils"
 import { StepResponse, createStep } from "@medusajs/workflows-sdk"
 
-type StepInput = CreateServiceZoneDTO[]
-
 export const createServiceZonesStepId = "create-service-zones"
+/**
+ * This step creates one or more service zones.
+ */
 export const createServiceZonesStep = createStep(
   createServiceZonesStepId,
-  async (input: StepInput, { container }) => {
+  async (input: CreateServiceZoneDTO[], { container }) => {
     const service = container.resolve<IFulfillmentModuleService>(
       ModuleRegistrationName.FULFILLMENT
     )

packages/core/core-flows/src/fulfillment/steps/create-shipping-option-rules.ts

@@ -6,6 +6,9 @@ import { ModuleRegistrationName } from "@medusajs/utils"
 import { StepResponse, createStep } from "@medusajs/workflows-sdk"
 
 export const createShippingOptionRulesStepId = "create-shipping-option-rules"
+/**
+ * This step creates one or more shipping option rules.
+ */
 export const createShippingOptionRulesStep = createStep(
   createShippingOptionRulesStepId,
   async (

packages/core/core-flows/src/fulfillment/steps/create-shipping-profiles.ts

@@ -5,12 +5,13 @@ import {
 import { ModuleRegistrationName } from "@medusajs/utils"
 import { StepResponse, createStep } from "@medusajs/workflows-sdk"
 
-type StepInput = CreateShippingProfileDTO[]
-
 export const createShippingProfilesStepId = "create-shipping-profiles"
+/**
+ * This step creates one or more shipping profiles.
+ */
 export const createShippingProfilesStep = createStep(
   createShippingProfilesStepId,
-  async (input: StepInput, { container }) => {
+  async (input: CreateShippingProfileDTO[], { container }) => {
     const service = container.resolve<IFulfillmentModuleService>(
       ModuleRegistrationName.FULFILLMENT
     )

packages/core/core-flows/src/fulfillment/steps/delete-fulfillment-sets.ts

@@ -3,6 +3,9 @@ import { ModuleRegistrationName } from "@medusajs/utils"
 import { createStep, StepResponse } from "@medusajs/workflows-sdk"
 
 export const deleteFulfillmentSetsStepId = "delete-fulfillment-sets"
+/**
+ * This step deletes one or more fulfillment sets.
+ */
 export const deleteFulfillmentSetsStep = createStep(
   deleteFulfillmentSetsStepId,
   async (ids: string[], { container }) => {

packages/core/core-flows/src/fulfillment/steps/delete-service-zones.ts

@@ -3,6 +3,9 @@ import { ModuleRegistrationName } from "@medusajs/utils"
 import { StepResponse, createStep } from "@medusajs/workflows-sdk"
 
 export const deleteServiceZonesStepId = "delete-service-zones"
+/**
+ * This step deletes one or more service zones.
+ */
 export const deleteServiceZonesStep = createStep(
   deleteServiceZonesStepId,
   async (ids: string[], { container }) => {

packages/core/core-flows/src/fulfillment/steps/delete-shipping-option-rules.ts

@@ -7,6 +7,9 @@ import { ModuleRegistrationName } from "@medusajs/utils"
 import { StepResponse, createStep } from "@medusajs/workflows-sdk"
 
 export const deleteShippingOptionRulesStepId = "delete-shipping-option-rules"
+/**
+ * This step deletes one or more shipping option rules.
+ */
 export const deleteShippingOptionRulesStep = createStep(
   deleteShippingOptionRulesStepId,
   async (

packages/core/core-flows/src/fulfillment/steps/delete-shipping-options.ts

@@ -4,6 +4,9 @@ import { ModuleRegistrationName, Modules } from "@medusajs/utils"
 import { createStep, StepResponse } from "@medusajs/workflows-sdk"
 
 export const deleteShippingOptionsStepId = "delete-shipping-options-step"
+/**
+ * This step deletes one or more shipping options.
+ */
 export const deleteShippingOptionsStep = createStep(
   deleteShippingOptionsStepId,
   async (ids: string[], { container }) => {

packages/core/core-flows/src/fulfillment/steps/set-shipping-options-price-sets.ts

@@ -9,7 +9,7 @@ import {
   remoteQueryObjectFromString,
 } from "@medusajs/utils"
 
-type SetShippingOptionsPriceSetsStepInput = {
+export type SetShippingOptionsPriceSetsStepInput = {
   id: string
   price_sets?: string[]
 }[]
@@ -56,6 +56,9 @@ async function getCurrentShippingOptionPriceSetsLinks(
 
 export const setShippingOptionsPriceSetsStepId =
   "set-shipping-options-price-sets-step"
+/**
+ * This step sets the price sets of one or more shipping options.
+ */
 export const setShippingOptionsPriceSetsStep = createStep(
   setShippingOptionsPriceSetsStepId,
   async (data: SetShippingOptionsPriceSetsStepInput, { container }) => {

packages/core/core-flows/src/fulfillment/steps/set-shipping-options-prices.ts

@@ -22,7 +22,7 @@ interface PriceRegionId {
   amount: number
 }
 
-type SetShippingOptionsPricesStepInput = {
+export type SetShippingOptionsPricesStepInput = {
   id: string
   prices?: FulfillmentWorkflow.UpdateShippingOptionsWorkflowInput["prices"]
 }[]
@@ -89,6 +89,9 @@ function buildPrices(
 }
 
 export const setShippingOptionsPricesStepId = "set-shipping-options-prices-step"
+/**
+ * This step sets the prices of one or more shipping options.
+ */
 export const setShippingOptionsPricesStep = createStep(
   setShippingOptionsPricesStepId,
   async (data: SetShippingOptionsPricesStepInput, { container }) => {

packages/core/core-flows/src/fulfillment/steps/update-fulfillment.ts

@@ -6,6 +6,9 @@ import {
 import { StepResponse, createStep } from "@medusajs/workflows-sdk"
 
 export const updateFulfillmentStepId = "update-fulfillment"
+/**
+ * This step updates a fulfillment.
+ */
 export const updateFulfillmentStep = createStep(
   updateFulfillmentStepId,
   async (

packages/core/core-flows/src/fulfillment/steps/update-service-zones.ts

@@ -5,12 +5,13 @@ import {
 } from "@medusajs/utils"
 import { StepResponse, createStep } from "@medusajs/workflows-sdk"
 
-type StepInput = FulfillmentWorkflow.UpdateServiceZonesWorkflowInput
-
 export const updateServiceZonesStepId = "update-service-zones"
+/**
+ * This step updates service zones matching the specified filters.
+ */
 export const updateServiceZonesStep = createStep(
   updateServiceZonesStepId,
-  async (input: StepInput, { container }) => {
+  async (input: FulfillmentWorkflow.UpdateServiceZonesWorkflowInput, { container }) => {
     const service = container.resolve<IFulfillmentModuleService>(
       ModuleRegistrationName.FULFILLMENT
     )

packages/core/core-flows/src/fulfillment/steps/update-shipping-option-rules.ts

@@ -7,6 +7,9 @@ import { ModuleRegistrationName } from "@medusajs/utils"
 import { StepResponse, createStep } from "@medusajs/workflows-sdk"
 
 export const updateShippingOptionRulesStepId = "update-shipping-option-rules"
+/**
+ * This step updates one or more shipping option rules.
+ */
 export const updateShippingOptionRulesStep = createStep(
   updateShippingOptionRulesStepId,
   async (

packages/core/core-flows/src/fulfillment/steps/update-shipping-profiles.ts

@@ -9,15 +9,18 @@ import {
 } from "@medusajs/utils"
 import { StepResponse, createStep } from "@medusajs/workflows-sdk"
 
-type StepInput = {
+export type UpdateShippingProfilesStepInput = {
   update: UpdateShippingProfileDTO
   selector: FilterableShippingProfileProps
 }
 
 export const updateShippingProfilesStepId = "update-shipping-profiles"
+/**
+ * This step updates shipping profiles matching the specified filters.
+ */
 export const updateShippingProfilesStep = createStep(
   updateShippingProfilesStepId,
-  async (input: StepInput, { container }) => {
+  async (input: UpdateShippingProfilesStepInput, { container }) => {
     const service = container.resolve<IFulfillmentModuleService>(
       ModuleRegistrationName.FULFILLMENT
     )

packages/core/core-flows/src/fulfillment/steps/upsert-shipping-options.ts

@@ -11,16 +11,19 @@ import {
 } from "@medusajs/utils"
 import { StepResponse, createStep } from "@medusajs/workflows-sdk"
 
-type StepInput = Omit<
+export type UpsertShippingOptionsStepInput = Omit<
   | FulfillmentWorkflow.CreateShippingOptionsWorkflowInput
   | FulfillmentWorkflow.UpdateShippingOptionsWorkflowInput,
   "prices"
 >[]
 
 export const upsertShippingOptionsStepId = "create-shipping-options-step"
+/**
+ * This step creates or updates shipping options.
+ */
 export const upsertShippingOptionsStep = createStep(
   upsertShippingOptionsStepId,
-  async (input: StepInput, { container }) => {
+  async (input: UpsertShippingOptionsStepInput, { container }) => {
     if (!input?.length) {
       return new StepResponse([], {})
     }

packages/core/core-flows/src/fulfillment/steps/validate-fulfillment-providers.ts

@@ -7,7 +7,7 @@ import {
 } from "@medusajs/utils"
 import { StepResponse, createStep } from "@medusajs/workflows-sdk"
 
-type FulfillmentProviderValidationInput = {
+export type FulfillmentProviderValidationWorkflowInput = {
   id?: string
   service_zone_id?: string
   provider_id?: string
@@ -15,9 +15,13 @@ type FulfillmentProviderValidationInput = {
 
 export const validateFulfillmentProvidersStepId =
   "validate-fulfillment-providers-step"
+/**
+ * This step validates that the specified fulfillment providers are available in the
+ * specified service zones.
+ */
 export const validateFulfillmentProvidersStep = createStep(
   validateFulfillmentProvidersStepId,
-  async (input: FulfillmentProviderValidationInput[], { container }) => {
+  async (input: FulfillmentProviderValidationWorkflowInput[], { container }) => {
     const dataToValidate: {
       service_zone_id: string
       provider_id: string

packages/core/core-flows/src/fulfillment/steps/validate-shipment.ts

@@ -3,6 +3,9 @@ import { MedusaError, ModuleRegistrationName } from "@medusajs/utils"
 import { createStep, StepResponse } from "@medusajs/workflows-sdk"
 
 export const validateShipmentStepId = "validate-shipment"
+/**
+ * This step validates that a shipment can be created for a fulfillment.
+ */
 export const validateShipmentStep = createStep(
   validateShipmentStepId,
   async (id: string, { container }) => {

packages/core/core-flows/src/inventory/workflows/bulk-create-delete-levels.ts

@@ -9,17 +9,20 @@ import {
   deleteInventoryLevelsFromItemAndLocationsStep,
 } from "../steps"
 
-interface WorkflowInput {
+export interface BulkCreateDeleteLevelsWorkflowInput {
   creates: InventoryTypes.CreateInventoryLevelInput[]
   deletes: { inventory_item_id: string; location_id: string }[]
 }
 
 export const bulkCreateDeleteLevelsWorkflowId =
   "bulk-create-delete-levels-workflow"
+/**
+ * This workflow creates and deletes inventory levels.
+ */
 export const bulkCreateDeleteLevelsWorkflow = createWorkflow(
   bulkCreateDeleteLevelsWorkflowId,
   (
-    input: WorkflowData<WorkflowInput>
+    input: WorkflowData<BulkCreateDeleteLevelsWorkflowInput>
   ): WorkflowResponse<InventoryLevelDTO[]> => {
     deleteInventoryLevelsFromItemAndLocationsStep(input.deletes)
 

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

@@ -13,13 +13,13 @@ type LocationLevelWithoutInventory = Omit<
   InventoryTypes.CreateInventoryLevelInput,
   "inventory_item_id"
 >
-interface WorkflowInput {
+export interface CreateInventoryItemsWorkflowInput {
   items: (InventoryTypes.CreateInventoryItemInput & {
     location_levels?: LocationLevelWithoutInventory[]
   })[]
 }
 
-const buildLocationLevelMapAndItemData = (data: WorkflowInput) => {
+const buildLocationLevelMapAndItemData = (data: CreateInventoryItemsWorkflowInput) => {
   data.items = data.items ?? []
   const inventoryItems: InventoryTypes.CreateInventoryItemInput[] = []
   // Keep an index to location levels mapping to inject the created inventory item
@@ -66,9 +66,12 @@ const buildInventoryLevelsInput = (data: {
 }
 
 export const createInventoryItemsWorkflowId = "create-inventory-items-workflow"
+/**
+ * This workflow creates one or more inventory items.
+ */
 export const createInventoryItemsWorkflow = createWorkflow(
   createInventoryItemsWorkflowId,
-  (input: WorkflowData<WorkflowInput>) => {
+  (input: WorkflowData<CreateInventoryItemsWorkflowInput>) => {
     const { locationLevelMap, inventoryItems } = transform(
       input,
       buildLocationLevelMapAndItemData

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

@@ -9,15 +9,18 @@ import {
   validateInventoryLocationsStep,
 } from "../steps"
 
-interface WorkflowInput {
+export interface CreateInventoryLevelsWorkflowInput {
   inventory_levels: InventoryTypes.CreateInventoryLevelInput[]
 }
 export const createInventoryLevelsWorkflowId =
   "create-inventory-levels-workflow"
+/**
+ * This workflow creates one or more inventory levels.
+ */
 export const createInventoryLevelsWorkflow = createWorkflow(
   createInventoryLevelsWorkflowId,
   (
-    input: WorkflowData<WorkflowInput>
+    input: WorkflowData<CreateInventoryLevelsWorkflowInput>
   ): WorkflowResponse<InventoryLevelDTO[]> => {
     validateInventoryLocationsStep(input.inventory_levels)
 

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

@@ -9,6 +9,9 @@ import { removeRemoteLinkStep } from "../../common/steps/remove-remote-links"
 import { Modules } from "@medusajs/utils"
 
 export const deleteInventoryItemWorkflowId = "delete-inventory-item-workflow"
+/**
+ * This workflow deletes one or more inventory items.
+ */
 export const deleteInventoryItemWorkflow = createWorkflow(
   deleteInventoryItemWorkflowId,
   (input: WorkflowData<string[]>): WorkflowResponse<string[]> => {

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

@@ -6,14 +6,17 @@ import {
 
 import { deleteInventoryLevelsStep } from "../steps"
 
-interface WorkflowInput {
+export interface DeleteInventoryLevelsWorkflowInput {
   ids: string[]
 }
 export const deleteInventoryLevelsWorkflowId =
   "delete-inventory-levels-workflow"
+/**
+ * This workflow deletes one or more inventory levels.
+ */
 export const deleteInventoryLevelsWorkflow = createWorkflow(
   deleteInventoryLevelsWorkflowId,
-  (input: WorkflowData<WorkflowInput>): WorkflowResponse<string[]> => {
+  (input: WorkflowData<DeleteInventoryLevelsWorkflowInput>): WorkflowResponse<string[]> => {
     return new WorkflowResponse(deleteInventoryLevelsStep(input.ids))
   }
 )

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

@@ -7,14 +7,17 @@ import {
 import { InventoryTypes } from "@medusajs/types"
 import { updateInventoryItemsStep } from "../steps"
 
-interface WorkflowInput {
+export interface UpdateInventoryItemsWorkflowInput {
   updates: InventoryTypes.UpdateInventoryItemInput[]
 }
 export const updateInventoryItemsWorkflowId = "update-inventory-items-workflow"
+/**
+ * This workflow updates one or more inventory items.
+ */
 export const updateInventoryItemsWorkflow = createWorkflow(
   updateInventoryItemsWorkflowId,
   (
-    input: WorkflowData<WorkflowInput>
+    input: WorkflowData<UpdateInventoryItemsWorkflowInput>
   ): WorkflowResponse<InventoryTypes.InventoryItemDTO[]> => {
     return new WorkflowResponse(updateInventoryItemsStep(input.updates))
   }

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

@@ -7,15 +7,18 @@ import {
 
 import { updateInventoryLevelsStep } from "../steps/update-inventory-levels"
 
-interface WorkflowInput {
+export interface UpdateInventoryLevelsWorkflowInput {
   updates: InventoryTypes.BulkUpdateInventoryLevelInput[]
 }
 export const updateInventoryLevelsWorkflowId =
   "update-inventory-levels-workflow"
+/**
+ * This workflow updates one or more inventory levels.
+ */
 export const updateInventoryLevelsWorkflow = createWorkflow(
   updateInventoryLevelsWorkflowId,
   (
-    input: WorkflowData<WorkflowInput>
+    input: WorkflowData<UpdateInventoryLevelsWorkflowInput>
   ): WorkflowResponse<InventoryLevelDTO[]> => {
     return new WorkflowResponse(updateInventoryLevelsStep(input.updates))
   }