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

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 3/n

packages/core/core-flows/src/definition/cart/steps/find-one-or-any-region.ts

@@ -3,6 +3,9 @@ import { MedusaError, ModuleRegistrationName } from "@medusajs/utils"
 import { StepResponse, createStep } from "@medusajs/workflows-sdk"
 
 export const findOneOrAnyRegionStepId = "find-one-or-any-region"
+/**
+ * This step retrieves a region either by the provided ID or the first region in the first store.
+ */
 export const findOneOrAnyRegionStep = createStep(
   findOneOrAnyRegionStepId,
   async (data: { regionId?: string }, { container }) => {

packages/core/core-flows/src/definition/cart/steps/find-or-create-customer.ts

@@ -2,12 +2,12 @@ import { CustomerDTO, ICustomerModuleService } from "@medusajs/types"
 import { ModuleRegistrationName, validateEmail } from "@medusajs/utils"
 import { StepResponse, createStep } from "@medusajs/workflows-sdk"
 
-interface StepInput {
+export interface FindOrCreateCustomerStepInput {
   customerId?: string | null
   email?: string | null
 }
 
-interface StepOutput {
+export interface FindOrCreateCustomerOutputStepOutput {
   customer?: CustomerDTO | null
   email?: string | null
 }
@@ -18,9 +18,13 @@ interface StepCompensateInput {
 }
 
 export const findOrCreateCustomerStepId = "find-or-create-customer"
+/**
+ * This step either finds a customer matching the specified ID, or finds / create a customer 
+ * matching the specified email. If both ID and email are provided, ID takes precedence.
+ */
 export const findOrCreateCustomerStep = createStep(
   findOrCreateCustomerStepId,
-  async (data: StepInput, { container }) => {
+  async (data: FindOrCreateCustomerStepInput, { container }) => {
     if (
       typeof data.customerId === undefined &&
       typeof data.email === undefined
@@ -38,7 +42,7 @@ export const findOrCreateCustomerStep = createStep(
       ModuleRegistrationName.CUSTOMER
     )
 
-    const customerData: StepOutput = {
+    const customerData: FindOrCreateCustomerOutputStepOutput = {
       customer: null,
       email: null,
     }

packages/core/core-flows/src/definition/cart/steps/find-sales-channel.ts

@@ -6,14 +6,18 @@ import {
 import { MedusaError, ModuleRegistrationName, isDefined } from "@medusajs/utils"
 import { StepResponse, createStep } from "@medusajs/workflows-sdk"
 
-interface StepInput {
+export interface FindSalesChannelStepInput {
   salesChannelId?: string | null
 }
 
 export const findSalesChannelStepId = "find-sales-channel"
+/**
+ * This step either retrieves a sales channel either using the ID provided as an input, or, if no ID
+ * is provided, the default sales channel of the first store.
+ */
 export const findSalesChannelStep = createStep(
   findSalesChannelStepId,
-  async (data: StepInput, { container }) => {
+  async (data: FindSalesChannelStepInput, { container }) => {
     const salesChannelService = container.resolve<ISalesChannelModuleService>(
       ModuleRegistrationName.SALES_CHANNEL
     )

packages/core/core-flows/src/definition/cart/steps/get-actions-to-compute-from-promotions.ts

@@ -2,16 +2,20 @@ import { CartDTO, IPromotionModuleService } from "@medusajs/types"
 import { ModuleRegistrationName } from "@medusajs/utils"
 import { StepResponse, createStep } from "@medusajs/workflows-sdk"
 
-interface StepInput {
+export interface GetActionsToComputeFromPromotionsStepInput {
   cart: CartDTO
   promotionCodesToApply: string[]
 }
 
 export const getActionsToComputeFromPromotionsStepId =
   "get-actions-to-compute-from-promotions"
+/**
+ * This step retrieves the actions to compute based on the promotions
+ * applied on a cart.
+ */
 export const getActionsToComputeFromPromotionsStep = createStep(
   getActionsToComputeFromPromotionsStepId,
-  async (data: StepInput, { container }) => {
+  async (data: GetActionsToComputeFromPromotionsStepInput, { container }) => {
     const { cart, promotionCodesToApply = [] } = data
     const promotionService = container.resolve<IPromotionModuleService>(
       ModuleRegistrationName.PROMOTION

packages/core/core-flows/src/definition/cart/steps/get-item-tax-lines.ts

@@ -12,7 +12,7 @@ import {
 import { MedusaError, ModuleRegistrationName } from "@medusajs/utils"
 import { StepResponse, createStep } from "@medusajs/workflows-sdk"
 
-interface StepInput {
+export interface GetItemTaxLinesStepInput {
   cart: CartWorkflowDTO
   items: CartLineItemDTO[]
   shipping_methods: CartShippingMethodDTO[]
@@ -94,9 +94,12 @@ function normalizeLineItemsForShipping(
 }
 
 export const getItemTaxLinesStepId = "get-item-tax-lines"
+/**
+ * This step retrieves the tax lines of the specified line items in a cart.
+ */
 export const getItemTaxLinesStep = createStep(
   getItemTaxLinesStepId,
-  async (data: StepInput, { container }) => {
+  async (data: GetItemTaxLinesStepInput, { container }) => {
     const {
       cart,
       items,

packages/core/core-flows/src/definition/cart/steps/get-line-item-actions.ts

@@ -12,15 +12,19 @@ import {
 } from "@medusajs/utils"
 import { StepResponse, createStep } from "@medusajs/workflows-sdk"
 
-interface StepInput {
+export interface GetLineItemActionsStepInput {
   id: string
   items: CreateLineItemForCartDTO[]
 }
 
 export const getLineItemActionsStepId = "get-line-item-actions-step"
+/**
+ * This step returns lists of cart line items to create or update based on the 
+ * provided input.
+ */
 export const getLineItemActionsStep = createStep(
   getLineItemActionsStepId,
-  async (data: StepInput, { container }) => {
+  async (data: GetLineItemActionsStepInput, { container }) => {
     const cartModule = container.resolve<ICartModuleService>(
       ModuleRegistrationName.CART
     )

packages/core/core-flows/src/definition/cart/steps/get-promotion-codes-to-apply.ts

@@ -2,7 +2,7 @@ import { IPromotionModuleService } from "@medusajs/types"
 import { ModuleRegistrationName, PromotionActions } from "@medusajs/utils"
 import { StepResponse, createStep } from "@medusajs/workflows-sdk"
 
-interface StepInput {
+export interface GetPromotionCodesToApplyStepInput {
   cart: {
     items?: { adjustments?: { code?: string }[] }[]
     shipping_methods?: { adjustments?: { code?: string }[] }[]
@@ -15,9 +15,12 @@ interface StepInput {
 }
 
 export const getPromotionCodesToApplyId = "get-promotion-codes-to-apply"
+/**
+ * This step retrieves the promotion codes to apply on a cart.
+ */
 export const getPromotionCodesToApply = createStep(
   getPromotionCodesToApplyId,
-  async (data: StepInput, { container }) => {
+  async (data: GetPromotionCodesToApplyStepInput, { container }) => {
     const { promo_codes = [], cart, action = PromotionActions.ADD } = data
     const { items = [], shipping_methods = [] } = cart
     const adjustmentCodes: string[] = []

packages/core/core-flows/src/definition/cart/steps/get-variant-price-sets.ts

@@ -2,15 +2,18 @@ import { IPricingModuleService } from "@medusajs/types"
 import { MedusaError, ModuleRegistrationName } from "@medusajs/utils"
 import { StepResponse, createStep } from "@medusajs/workflows-sdk"
 
-interface StepInput {
+export interface GetVariantPriceSetsStepInput {
   variantIds: string[]
   context?: Record<string, unknown>
 }
 
 export const getVariantPriceSetsStepId = "get-variant-price-sets"
+/**
+ * This step retrieves the calculated price sets of the specified variants.
+ */
 export const getVariantPriceSetsStep = createStep(
   getVariantPriceSetsStepId,
-  async (data: StepInput, { container }) => {
+  async (data: GetVariantPriceSetsStepInput, { container }) => {
     if (!data.variantIds.length) {
       return new StepResponse({})
     }

packages/core/core-flows/src/definition/cart/steps/get-variants.ts

@@ -7,15 +7,18 @@ import {
 import { ModuleRegistrationName } from "@medusajs/utils"
 import { StepResponse, createStep } from "@medusajs/workflows-sdk"
 
-interface StepInput {
+export interface GetVariantsStepInput {
   filter?: FilterableProductVariantProps
   config?: FindConfig<ProductVariantDTO>
 }
 
 export const getVariantsStepId = "get-variants"
+/**
+ * This step retrieves variants matching the specified filters.
+ */
 export const getVariantsStep = createStep(
   getVariantsStepId,
-  async (data: StepInput, { container }) => {
+  async (data: GetVariantsStepInput, { container }) => {
     const productModuleService = container.resolve<IProductModuleService>(
       ModuleRegistrationName.PRODUCT
     )

packages/core/core-flows/src/definition/cart/steps/prepare-adjustments-from-promotion-actions.ts

@@ -10,15 +10,19 @@ import {
 import { ComputedActions, ModuleRegistrationName } from "@medusajs/utils"
 import { StepResponse, createStep } from "@medusajs/workflows-sdk"
 
-interface StepInput {
+export interface PrepareAdjustmentsFromPromotionActionsStepInput {
   actions: ComputeActions[]
 }
 
 export const prepareAdjustmentsFromPromotionActionsStepId =
   "prepare-adjustments-from-promotion-actions"
+/**
+ * This step prepares the line item or shipping method adjustments using
+ * actions computed by the Promotion Module.
+ */
 export const prepareAdjustmentsFromPromotionActionsStep = createStep(
   prepareAdjustmentsFromPromotionActionsStepId,
-  async (data: StepInput, { container }) => {
+  async (data: PrepareAdjustmentsFromPromotionActionsStepInput, { container }) => {
     const promotionModuleService: IPromotionModuleService = container.resolve(
       ModuleRegistrationName.PROMOTION
     )

packages/core/core-flows/src/definition/cart/steps/refresh-cart-promotions.ts

@@ -2,7 +2,7 @@ import { PromotionActions } from "@medusajs/utils"
 import { StepResponse, createStep } from "@medusajs/workflows-sdk"
 import { updateCartPromotionsWorkflow } from "../workflows"
 
-interface StepInput {
+export interface RefreshCartPromotionsStepInput {
   id: string
   promo_codes?: string[]
   action?:
@@ -12,9 +12,12 @@ interface StepInput {
 }
 
 export const refreshCartPromotionsStepId = "refresh-cart-promotions"
+/**
+ * This step refreshes the promotions of a cart.
+ */
 export const refreshCartPromotionsStep = createStep(
   refreshCartPromotionsStepId,
-  async (data: StepInput, { container }) => {
+  async (data: RefreshCartPromotionsStepInput, { container }) => {
     const { promo_codes = [], id, action = PromotionActions.ADD } = data
 
     await updateCartPromotionsWorkflow(container).run({

packages/core/core-flows/src/definition/cart/steps/refresh-cart-shipping-methods.ts

@@ -6,14 +6,17 @@ import {
 import { ModuleRegistrationName, arrayDifference } from "@medusajs/utils"
 import { StepResponse, createStep } from "@medusajs/workflows-sdk"
 
-interface StepInput {
+export interface RefreshCartShippingMethodsStepInput {
   cart: CartDTO
 }
 
 export const refreshCartShippingMethodsStepId = "refresh-cart-shipping-methods"
+/**
+ * This step refreshes the shipping methods of a cart.
+ */
 export const refreshCartShippingMethodsStep = createStep(
   refreshCartShippingMethodsStepId,
-  async (data: StepInput, { container }) => {
+  async (data: RefreshCartShippingMethodsStepInput, { container }) => {
     const { cart } = data
     const { shipping_methods: shippingMethods = [] } = cart
 

packages/core/core-flows/src/definition/cart/steps/remove-line-item-adjustments.ts

@@ -2,14 +2,17 @@ import { ICartModuleService } from "@medusajs/types"
 import { ModuleRegistrationName } from "@medusajs/utils"
 import { StepResponse, createStep } from "@medusajs/workflows-sdk"
 
-interface StepInput {
+export interface RemoveLineItemAdjustmentsStepInput {
   lineItemAdjustmentIdsToRemove: string[]
 }
 
 export const removeLineItemAdjustmentsStepId = "remove-line-item-adjustments"
+/**
+ * This step removes line item adjustments from a cart.
+ */
 export const removeLineItemAdjustmentsStep = createStep(
   removeLineItemAdjustmentsStepId,
-  async (data: StepInput, { container }) => {
+  async (data: RemoveLineItemAdjustmentsStepInput, { container }) => {
     const { lineItemAdjustmentIdsToRemove = [] } = data
     const cartModuleService: ICartModuleService = container.resolve(
       ModuleRegistrationName.CART

packages/core/core-flows/src/definition/cart/steps/remove-shipping-method-adjustments.ts

@@ -2,15 +2,18 @@ import { ICartModuleService } from "@medusajs/types"
 import { ModuleRegistrationName } from "@medusajs/utils"
 import { StepResponse, createStep } from "@medusajs/workflows-sdk"
 
-interface StepInput {
+export interface RemoveShippingMethodAdjustmentsStepInput {
   shippingMethodAdjustmentIdsToRemove: string[]
 }
 
 export const removeShippingMethodAdjustmentsStepId =
   "remove-shipping-method-adjustments"
+/**
+ * This step removes shipping method adjustments from a cart.
+ */
 export const removeShippingMethodAdjustmentsStep = createStep(
   removeShippingMethodAdjustmentsStepId,
-  async (data: StepInput, { container }) => {
+  async (data: RemoveShippingMethodAdjustmentsStepInput, { container }) => {
     const { shippingMethodAdjustmentIdsToRemove = [] } = data
     const cartModuleService: ICartModuleService = container.resolve(
       ModuleRegistrationName.CART

packages/core/core-flows/src/definition/cart/steps/remove-shipping-method-from-cart.ts

@@ -2,15 +2,18 @@ import { ICartModuleService } from "@medusajs/types"
 import { ModuleRegistrationName } from "@medusajs/utils"
 import { StepResponse, createStep } from "@medusajs/workflows-sdk"
 
-interface StepInput {
+export interface RemoveShippingMethodFromCartStepInput {
   shipping_method_ids: string[]
 }
 
 export const removeShippingMethodFromCartStepId =
   "remove-shipping-method-to-cart-step"
+/**
+ * This step removes shipping methods from a cart.
+ */
 export const removeShippingMethodFromCartStep = createStep(
   removeShippingMethodFromCartStepId,
-  async (data: StepInput, { container }) => {
+  async (data: RemoveShippingMethodFromCartStepInput, { container }) => {
     const cartService = container.resolve<ICartModuleService>(
       ModuleRegistrationName.CART
     )

packages/core/core-flows/src/definition/cart/steps/reserve-inventory.ts

@@ -2,7 +2,7 @@ import { IInventoryService } from "@medusajs/types"
 import { MathBN, ModuleRegistrationName } from "@medusajs/utils"
 import { StepResponse, createStep } from "@medusajs/workflows-sdk"
 
-interface StepInput {
+export interface ReserveVariantInventoryStepInput {
   items: {
     id?: string
     inventory_item_id: string
@@ -14,9 +14,13 @@ interface StepInput {
 }
 
 export const reserveInventoryStepId = "reserve-inventory-step"
+/**
+ * This step reserves the quantity of line items from the associated
+ * variant's inventory.
+ */
 export const reserveInventoryStep = createStep(
   reserveInventoryStepId,
-  async (data: StepInput, { container }) => {
+  async (data: ReserveVariantInventoryStepInput, { container }) => {
     const inventoryService = container.resolve<IInventoryService>(
       ModuleRegistrationName.INVENTORY
     )

packages/core/core-flows/src/definition/cart/steps/retrieve-cart-with-links.ts

@@ -7,15 +7,18 @@ import {
 } from "@medusajs/utils"
 import { StepResponse, createStep } from "@medusajs/workflows-sdk"
 
-interface StepInput {
+export interface RetrieveCartWithLinksStepInput {
   cart_or_cart_id: string | CartWorkflowDTO
   fields: string[]
 }
 
 export const retrieveCartWithLinksStepId = "retrieve-cart-with-links"
+/**
+ * This step retrieves a cart's details with its linked records.
+ */
 export const retrieveCartWithLinksStep = createStep(
   retrieveCartWithLinksStepId,
-  async (data: StepInput, { container }) => {
+  async (data: RetrieveCartWithLinksStepInput, { container }) => {
     const { cart_or_cart_id: cartOrCartId, fields } = data
 
     if (isObject(cartOrCartId)) {

packages/core/core-flows/src/definition/cart/steps/retrieve-cart.ts

@@ -2,15 +2,18 @@ import { CartDTO, FindConfig, ICartModuleService } from "@medusajs/types"
 import { ModuleRegistrationName } from "@medusajs/utils"
 import { StepResponse, createStep } from "@medusajs/workflows-sdk"
 
-interface StepInput {
+export interface RetrieveCartStepInput {
   id: string
   config?: FindConfig<CartDTO>
 }
 
 export const retrieveCartStepId = "retrieve-cart"
+/**
+ * This step retrieves a cart's details.
+ */
 export const retrieveCartStep = createStep(
   retrieveCartStepId,
-  async (data: StepInput, { container }) => {
+  async (data: RetrieveCartStepInput, { container }) => {
     const cartModuleService = container.resolve<ICartModuleService>(
       ModuleRegistrationName.CART
     )

packages/core/core-flows/src/definition/cart/steps/set-tax-lines-for-items.ts

@@ -9,16 +9,19 @@ import {
 import { ModuleRegistrationName } from "@medusajs/utils"
 import { StepResponse, createStep } from "@medusajs/workflows-sdk"
 
-interface StepInput {
+export interface SetTaxLinesForItemsStepInput {
   cart: CartWorkflowDTO
   item_tax_lines: ItemTaxLineDTO[]
   shipping_tax_lines: ShippingTaxLineDTO[]
 }
 
 export const setTaxLinesForItemsStepId = "set-tax-lines-for-items"
+/**
+ * This step sets the tax lines of shipping methods and line items in a cart.
+ */
 export const setTaxLinesForItemsStep = createStep(
   setTaxLinesForItemsStepId,
-  async (data: StepInput, { container }) => {
+  async (data: SetTaxLinesForItemsStepInput, { container }) => {
     const { cart, item_tax_lines, shipping_tax_lines } = data
     const cartService = container.resolve<ICartModuleService>(
       ModuleRegistrationName.CART

packages/core/core-flows/src/definition/cart/steps/update-cart-promotions.ts

@@ -7,7 +7,7 @@ import {
 } from "@medusajs/utils"
 import { StepResponse, createStep } from "@medusajs/workflows-sdk"
 
-interface StepInput {
+export interface UpdateCartPromotionStepInput {
   id: string
   promo_codes?: string[]
   action?:
@@ -17,9 +17,12 @@ interface StepInput {
 }
 
 export const updateCartPromotionsStepId = "update-cart-promotions"
+/**
+ * This step updates the promotions applied on a cart.
+ */
 export const updateCartPromotionsStep = createStep(
   updateCartPromotionsStepId,
-  async (data: StepInput, { container }) => {
+  async (data: UpdateCartPromotionStepInput, { container }) => {
     const { promo_codes = [], id, action = PromotionActions.ADD } = data
     const remoteLink = container.resolve(ContainerRegistrationKeys.REMOTE_LINK)
     const remoteQuery = container.resolve(

packages/core/core-flows/src/definition/cart/steps/update-carts.ts

@@ -10,6 +10,9 @@ import {
 import { StepResponse, createStep } from "@medusajs/workflows-sdk"
 
 export const updateCartsStepId = "update-carts"
+/**
+ * This step updates a cart.
+ */
 export const updateCartsStep = createStep(
   updateCartsStepId,
   async (data: UpdateCartWorkflowInputDTO[], { container }) => {

packages/core/core-flows/src/definition/cart/steps/update-line-items.ts

@@ -8,15 +8,18 @@ import {
 } from "@medusajs/utils"
 import { StepResponse, createStep } from "@medusajs/workflows-sdk"
 
-interface StepInput {
+export interface UpdateLineItemsStepInput {
   id: string
   items: UpdateLineItemWithSelectorDTO[]
 }
 
 export const updateLineItemsStepId = "update-line-items-step"
+/**
+ * This step updates a cart's line items.
+ */
 export const updateLineItemsStep = createStep(
   updateLineItemsStepId,
-  async (input: StepInput, { container }) => {
+  async (input: UpdateLineItemsStepInput, { container }) => {
     const { id, items = [] } = input
 
     if (!items?.length) {

packages/core/core-flows/src/definition/cart/steps/update-tax-lines.ts

@@ -6,7 +6,7 @@ import {
 import { StepResponse, createStep } from "@medusajs/workflows-sdk"
 import { updateTaxLinesWorkflow } from "../workflows"
 
-interface StepInput {
+export interface UpdateTaxLinesStepInput {
   cart_or_cart_id: CartWorkflowDTO | string
   items?: CartLineItemDTO[]
   shipping_methods?: CartShippingMethodDTO[]
@@ -14,9 +14,12 @@ interface StepInput {
 }
 
 export const updateTaxLinesStepId = "update-tax-lines-step"
+/**
+ * This step updates tax lines of line items and shipping methods.
+ */
 export const updateTaxLinesStep = createStep(
   updateTaxLinesStepId,
-  async (input: StepInput, { container }) => {
+  async (input: UpdateTaxLinesStepInput, { container }) => {
     const { transaction } = await updateTaxLinesWorkflow(container).run({
       input,
     })

packages/core/core-flows/src/definition/cart/steps/validate-cart-payments.ts

@@ -2,14 +2,18 @@ import { CartWorkflowDTO } from "@medusajs/types"
 import { isPresent, MedusaError, PaymentSessionStatus } from "@medusajs/utils"
 import { createStep, StepResponse } from "@medusajs/workflows-sdk"
 
-interface StepInput {
+export interface ValidateCartPaymentsStepInput {
   cart: CartWorkflowDTO
 }
 
 export const validateCartPaymentsStepId = "validate-cart-payments"
+/**
+ * This step validates a cart's payment sessions. Their status must
+ * be `pending` or `requires_more`.
+ */
 export const validateCartPaymentsStep = createStep(
   validateCartPaymentsStepId,
-  async (data: StepInput) => {
+  async (data: ValidateCartPaymentsStepInput) => {
     const {
       cart: { payment_collection: paymentCollection },
     } = data

packages/core/core-flows/src/definition/cart/steps/validate-cart-shipping-options.ts

@@ -6,7 +6,7 @@ import {
 } from "@medusajs/utils"
 import { StepResponse, createStep } from "@medusajs/workflows-sdk"
 
-interface StepInput {
+export interface ValidateCartShippingOptionsStepInput {
   cart: CartDTO
   shippingOptionsContext: {
     enabled_in_store?: "true" | "false"
@@ -17,9 +17,12 @@ interface StepInput {
 
 export const validateCartShippingOptionsStepId =
   "validate-cart-shipping-options"
+/**
+ * This step validates shipping options to ensure they can be applied on a cart.
+ */
 export const validateCartShippingOptionsStep = createStep(
   validateCartShippingOptionsStepId,
-  async (data: StepInput, { container }) => {
+  async (data: ValidateCartShippingOptionsStepInput, { container }) => {
     const { option_ids: optionIds = [], cart, shippingOptionsContext } = data
 
     if (!optionIds.length) {

packages/core/core-flows/src/definition/cart/steps/validate-variant-prices.ts

@@ -2,7 +2,7 @@ import { BigNumberInput } from "@medusajs/types"
 import { MedusaError, isPresent } from "@medusajs/utils"
 import { createStep } from "@medusajs/workflows-sdk"
 
-interface StepInput {
+export interface ValidateVariantPricesStepInput {
   variants: {
     id: string
     calculated_price?: {
@@ -12,9 +12,12 @@ interface StepInput {
 }
 
 export const validateVariantPricesStepId = "validate-variant-prices"
+/**
+ * This step validates the specified variant objects to ensure they have prices.
+ */
 export const validateVariantPricesStep = createStep(
   validateVariantPricesStepId,
-  async (data: StepInput, { container }) => {
+  async (data: ValidateVariantPricesStepInput, { container }) => {
     const priceNotFound: string[] = []
     for (const variant of data.variants) {
       if (!isPresent(variant?.calculated_price?.calculated_amount)) {