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

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

packages/core/core-flows/src/customer-group/steps/create-customer-groups.ts

@@ -3,6 +3,9 @@ import { ModuleRegistrationName } from "@medusajs/utils"
 import { StepResponse, createStep } from "@medusajs/workflows-sdk"
 
 export const createCustomerGroupsStepId = "create-customer-groups"
+/**
+ * This step creates one or more customer groups.
+ */
 export const createCustomerGroupsStep = createStep(
   createCustomerGroupsStepId,
   async (data: CreateCustomerGroupDTO[], { container }) => {

packages/core/core-flows/src/customer-group/steps/delete-customer-group-customers.ts

@@ -4,6 +4,9 @@ import { StepResponse, createStep } from "@medusajs/workflows-sdk"
 
 export const deleteCustomerGroupCustomersStepId =
   "delete-customer-group-customers"
+/**
+ * This step removes customers from groups.
+ */
 export const deleteCustomerGroupCustomersStep = createStep(
   deleteCustomerGroupCustomersStepId,
   async (data: GroupCustomerPair[], { container }) => {

packages/core/core-flows/src/customer-group/steps/delete-customer-groups.ts

@@ -2,12 +2,13 @@ import { ICustomerModuleService } from "@medusajs/types"
 import { ModuleRegistrationName } from "@medusajs/utils"
 import { createStep, StepResponse } from "@medusajs/workflows-sdk"
 
-type DeleteCustomerGroupStepInput = string[]
-
 export const deleteCustomerGroupStepId = "delete-customer-groups"
+/**
+ * This step deletes one or more customer groups.
+ */
 export const deleteCustomerGroupStep = createStep(
   deleteCustomerGroupStepId,
-  async (ids: DeleteCustomerGroupStepInput, { container }) => {
+  async (ids: string[], { container }) => {
     const service = container.resolve<ICustomerModuleService>(
       ModuleRegistrationName.CUSTOMER
     )

packages/core/core-flows/src/customer-group/steps/link-customers-customer-group.ts

@@ -4,6 +4,9 @@ import { StepResponse, createStep } from "@medusajs/workflows-sdk"
 
 export const linkCustomersToCustomerGroupStepId =
   "link-customers-to-customer-group"
+/**
+ * This step creates one or more links between customer and customer group records.
+ */
 export const linkCustomersToCustomerGroupStep = createStep(
   linkCustomersToCustomerGroupStepId,
   async (data: LinkWorkflowInput, { container }) => {

packages/core/core-flows/src/customer-group/steps/update-customer-groups.ts

@@ -10,12 +10,15 @@ import {
 } from "@medusajs/utils"
 import { StepResponse, createStep } from "@medusajs/workflows-sdk"
 
-type UpdateCustomerGroupStepInput = {
+export type UpdateCustomerGroupStepInput = {
   selector: FilterableCustomerGroupProps
   update: CustomerGroupUpdatableFields
 }
 
 export const updateCustomerGroupStepId = "update-customer-groups"
+/**
+ * This step updates one or more customer groups.
+ */
 export const updateCustomerGroupsStep = createStep(
   updateCustomerGroupStepId,
   async (data: UpdateCustomerGroupStepInput, { container }) => {

packages/core/core-flows/src/customer-group/workflows/create-customer-groups.ts

@@ -6,13 +6,16 @@ import {
 } from "@medusajs/workflows-sdk"
 import { createCustomerGroupsStep } from "../steps"
 
-type WorkflowInput = { customersData: CreateCustomerGroupDTO[] }
+export type CreateCustomerGroupsWorkflowInput = { customersData: CreateCustomerGroupDTO[] }
 
 export const createCustomerGroupsWorkflowId = "create-customer-groups"
+/**
+ * This workflow creates one or more customer groups.
+ */
 export const createCustomerGroupsWorkflow = createWorkflow(
   createCustomerGroupsWorkflowId,
   (
-    input: WorkflowData<WorkflowInput>
+    input: WorkflowData<CreateCustomerGroupsWorkflowInput>
   ): WorkflowResponse<CustomerGroupDTO[]> => {
     return new WorkflowResponse(createCustomerGroupsStep(input.customersData))
   }

packages/core/core-flows/src/customer-group/workflows/delete-customer-groups.ts

@@ -1,12 +1,15 @@
 import { WorkflowData, createWorkflow } from "@medusajs/workflows-sdk"
 import { deleteCustomerGroupStep } from "../steps"
 
-type WorkflowInput = { ids: string[] }
+export type DeleteCustomerGroupsWorkflowInput = { ids: string[] }
 
 export const deleteCustomerGroupsWorkflowId = "delete-customer-groups"
+/**
+ * This workflow deletes one or more customer groups.
+ */
 export const deleteCustomerGroupsWorkflow = createWorkflow(
   deleteCustomerGroupsWorkflowId,
-  (input: WorkflowData<WorkflowInput>): WorkflowData<void> => {
+  (input: WorkflowData<DeleteCustomerGroupsWorkflowInput>): WorkflowData<void> => {
     return deleteCustomerGroupStep(input.ids)
   }
 )

packages/core/core-flows/src/customer-group/workflows/link-customers-customer-group.ts

@@ -4,6 +4,9 @@ import { linkCustomersToCustomerGroupStep } from "../steps"
 
 export const linkCustomersToCustomerGroupWorkflowId =
   "link-customers-to-customer-group"
+/**
+ * This workflow creates one or more links between customer and customer group records.
+ */
 export const linkCustomersToCustomerGroupWorkflow = createWorkflow(
   linkCustomersToCustomerGroupWorkflowId,
   (input: WorkflowData<LinkWorkflowInput>): WorkflowData<void> => {

packages/core/core-flows/src/customer-group/workflows/update-customer-groups.ts

@@ -10,16 +10,19 @@ import {
 } from "@medusajs/workflows-sdk"
 import { updateCustomerGroupsStep } from "../steps"
 
-type WorkflowInput = {
+export type UpdateCustomerGroupsWorkflowInput = {
   selector: FilterableCustomerGroupProps
   update: CustomerGroupUpdatableFields
 }
 
 export const updateCustomerGroupsWorkflowId = "update-customer-groups"
+/**
+ * This workflow updates one or more customer groups.
+ */
 export const updateCustomerGroupsWorkflow = createWorkflow(
   updateCustomerGroupsWorkflowId,
   (
-    input: WorkflowData<WorkflowInput>
+    input: WorkflowData<UpdateCustomerGroupsWorkflowInput>
   ): WorkflowResponse<CustomerGroupDTO[]> => {
     return new WorkflowResponse(updateCustomerGroupsStep(input))
   }

packages/core/core-flows/src/defaults/steps/create-default-store.ts

@@ -8,6 +8,9 @@ type CreateDefaultStoreStepInput = {
 }
 
 export const createDefaultStoreStepId = "create-default-store"
+/**
+ * This step creates a default store.
+ */
 export const createDefaultStoreStep = createStep(
   createDefaultStoreStepId,
   async (data: CreateDefaultStoreStepInput, { container }) => {

packages/core/core-flows/src/defaults/workflows/create-defaults.ts

@@ -3,6 +3,9 @@ import { createDefaultSalesChannelStep } from "../../sales-channel"
 import { createDefaultStoreStep } from "../steps/create-default-store"
 
 export const createDefaultsWorkflowID = "create-defaults"
+/**
+ * This workflow creates default data for a Medusa application.
+ */
 export const createDefaultsWorkflow = createWorkflow(
   createDefaultsWorkflowID,
   () => {

packages/core/core-flows/src/definition/cart/steps/add-shipping-method-to-cart.ts

@@ -2,14 +2,17 @@ import { CreateShippingMethodDTO, ICartModuleService } from "@medusajs/types"
 import { ModuleRegistrationName } from "@medusajs/utils"
 import { StepResponse, createStep } from "@medusajs/workflows-sdk"
 
-interface StepInput {
+export interface AddShippingMethodToCartStepInput {
   shipping_methods: CreateShippingMethodDTO[]
 }
 
 export const addShippingMethodToCartStepId = "add-shipping-method-to-cart-step"
+/**
+ * This step adds shipping methods to a cart.
+ */
 export const addShippingMethodToCartStep = createStep(
   addShippingMethodToCartStepId,
-  async (data: StepInput, { container }) => {
+  async (data: AddShippingMethodToCartStepInput, { container }) => {
     const cartService = container.resolve<ICartModuleService>(
       ModuleRegistrationName.CART
     )

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

@@ -7,7 +7,7 @@ import {
 } from "@medusajs/utils"
 import { StepResponse, createStep } from "@medusajs/workflows-sdk"
 
-interface StepInput {
+export interface ConfirmVariantInventoryStepInput {
   items: {
     inventory_item_id: string
     required_quantity: number
@@ -18,9 +18,12 @@ interface StepInput {
 }
 
 export const confirmInventoryStepId = "confirm-inventory-step"
+/**
+ * This step confirms for one or more variants that their inventory has a required quantity.
+ */
 export const confirmInventoryStep = createStep(
   confirmInventoryStepId,
-  async (data: StepInput, { container }) => {
+  async (data: ConfirmVariantInventoryStepInput, { container }) => {
     const inventoryService = container.resolve<IInventoryService>(
       ModuleRegistrationName.INVENTORY
     )

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

@@ -3,6 +3,9 @@ import { ModuleRegistrationName } from "@medusajs/utils"
 import { StepResponse, createStep } from "@medusajs/workflows-sdk"
 
 export const createCartsStepId = "create-carts"
+/**
+ * This step creates a cart.
+ */
 export const createCartsStep = createStep(
   createCartsStepId,
   async (data: CreateCartDTO[], { container }) => {

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

@@ -5,14 +5,17 @@ import {
 import { ModuleRegistrationName } from "@medusajs/utils"
 import { StepResponse, createStep } from "@medusajs/workflows-sdk"
 
-interface StepInput {
+export interface CreateLineItemAdjustmentsCartStepInput {
   lineItemAdjustmentsToCreate: CreateLineItemAdjustmentDTO[]
 }
 
 export const createLineItemAdjustmentsStepId = "create-line-item-adjustments"
+/**
+ * This step creates line item adjustments in a cart.
+ */
 export const createLineItemAdjustmentsStep = createStep(
   createLineItemAdjustmentsStepId,
-  async (data: StepInput, { container }) => {
+  async (data: CreateLineItemAdjustmentsCartStepInput, { container }) => {
     const { lineItemAdjustmentsToCreate = [] } = data
     const cartModuleService: ICartModuleService = container.resolve(
       ModuleRegistrationName.CART

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

@@ -2,15 +2,18 @@ import { CreateLineItemForCartDTO, ICartModuleService } from "@medusajs/types"
 import { ModuleRegistrationName } from "@medusajs/utils"
 import { StepResponse, createStep } from "@medusajs/workflows-sdk"
 
-interface StepInput {
+export interface CreateLineItemsCartStepInput {
   id: string
   items: CreateLineItemForCartDTO[]
 }
 
 export const createLineItemsStepId = "create-line-items-step"
+/**
+ * This step creates line item in a cart.
+ */
 export const createLineItemsStep = createStep(
   createLineItemsStepId,
-  async (data: StepInput, { container }) => {
+  async (data: CreateLineItemsCartStepInput, { container }) => {
     const cartModule = container.resolve<ICartModuleService>(
       ModuleRegistrationName.CART
     )

packages/core/core-flows/src/definition/cart/steps/create-payment-collection.ts

@@ -2,7 +2,7 @@ import { BigNumberInput, IPaymentModuleService } from "@medusajs/types"
 import { ModuleRegistrationName } from "@medusajs/utils"
 import { StepResponse, createStep } from "@medusajs/workflows-sdk"
 
-type StepInput = {
+export type CreatePaymentCollectionCartStepInput = {
   region_id: string
   currency_code: string
   amount: BigNumberInput
@@ -10,9 +10,12 @@ type StepInput = {
 }
 
 export const createPaymentCollectionsStepId = "create-payment-collections"
+/**
+ * This step creates payment collections in a cart.
+ */
 export const createPaymentCollectionsStep = createStep(
   createPaymentCollectionsStepId,
-  async (data: StepInput[], { container }) => {
+  async (data: CreatePaymentCollectionCartStepInput[], { container }) => {
     const service = container.resolve<IPaymentModuleService>(
       ModuleRegistrationName.PAYMENT
     )

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

@@ -5,15 +5,18 @@ import {
 import { ModuleRegistrationName } from "@medusajs/utils"
 import { StepResponse, createStep } from "@medusajs/workflows-sdk"
 
-interface StepInput {
+export interface CreateShippingMethodAdjustmentsStepInput {
   shippingMethodAdjustmentsToCreate: CreateShippingMethodAdjustmentDTO[]
 }
 
 export const createShippingMethodAdjustmentsStepId =
   "create-shipping-method-adjustments"
+/**
+ * This step creates shipping method adjustments for a cart.
+ */
 export const createShippingMethodAdjustmentsStep = createStep(
   createShippingMethodAdjustmentsStepId,
-  async (data: StepInput, { container }) => {
+  async (data: CreateShippingMethodAdjustmentsStepInput, { container }) => {
     const { shippingMethodAdjustmentsToCreate = [] } = data
     const cartModuleService: ICartModuleService = container.resolve(
       ModuleRegistrationName.CART

packages/core/core-flows/src/definition/cart/workflows/add-shipping-method-to-cart.ts

@@ -13,7 +13,7 @@ import { refreshCartPromotionsStep } from "../steps/refresh-cart-promotions"
 import { updateTaxLinesStep } from "../steps/update-tax-lines"
 import { cartFieldsForRefreshSteps } from "../utils/fields"
 
-interface AddShippingMethodToCartWorkflowInput {
+export interface AddShippingMethodToCartWorkflowInput {
   cart_id: string
   options: {
     id: string
@@ -22,6 +22,9 @@ interface AddShippingMethodToCartWorkflowInput {
 }
 
 export const addShippingMethodToCartWorkflowId = "add-shipping-method-to-cart"
+/**
+ * This workflow adds shipping methods to a cart.
+ */
 export const addShippingMethodToWorkflow = createWorkflow(
   addShippingMethodToCartWorkflowId,
   (

packages/core/core-flows/src/definition/cart/workflows/add-to-cart.ts

@@ -28,6 +28,9 @@ import { confirmVariantInventoryWorkflow } from "./confirm-variant-inventory"
 import { refreshPaymentCollectionForCartWorkflow } from "./refresh-payment-collection"
 
 export const addToCartWorkflowId = "add-to-cart"
+/**
+ * This workflow adds items to a cart.
+ */
 export const addToCartWorkflow = createWorkflow(
   addToCartWorkflowId,
   (input: WorkflowData<AddToCartWorkflowInputDTO>) => {

packages/core/core-flows/src/definition/cart/workflows/complete-cart.ts

@@ -24,10 +24,17 @@ import {
   prepareTaxLinesData,
 } from "../utils/prepare-line-item-data"
 
+export type CompleteCartWorkflowInput = {
+  id: string
+}
+
 export const completeCartWorkflowId = "complete-cart"
+/**
+ * This workflow completes a cart.
+ */
 export const completeCartWorkflow = createWorkflow(
   completeCartWorkflowId,
-  (input: WorkflowData<any>): WorkflowResponse<OrderDTO> => {
+  (input: WorkflowData<CompleteCartWorkflowInput>): WorkflowResponse<OrderDTO> => {
     const cart = useRemoteQueryStep({
       entry_point: "cart",
       fields: completeCartFields,

packages/core/core-flows/src/definition/cart/workflows/confirm-variant-inventory.ts

@@ -8,7 +8,7 @@ import {
 import { confirmInventoryStep } from "../steps"
 import { prepareConfirmInventoryInput } from "../utils/prepare-confirm-inventory-input"
 
-interface Output {
+export interface ConfirmVariantInventoryWorkflowOutput {
   items: {
     id?: string
     inventory_item_id: string
@@ -20,11 +20,14 @@ interface Output {
 }
 
 export const confirmVariantInventoryWorkflowId = "confirm-item-inventory"
+/**
+ * This workflow confirms for one or more variants that their inventory has a required quantity.
+ */
 export const confirmVariantInventoryWorkflow = createWorkflow(
   confirmVariantInventoryWorkflowId,
   (
     input: WorkflowData<ConfirmVariantInventoryWorkflowInputDTO>
-  ): WorkflowResponse<Output> => {
+  ): WorkflowResponse<ConfirmVariantInventoryWorkflowOutput> => {
     const confirmInventoryInput = transform(
       { input },
       prepareConfirmInventoryInput

packages/core/core-flows/src/definition/cart/workflows/create-carts.ts

@@ -32,6 +32,9 @@ import { refreshPaymentCollectionForCartWorkflow } from "./refresh-payment-colle
 // - Refresh/delete shipping methods (fulfillment module)
 
 export const createCartWorkflowId = "create-cart"
+/**
+ * This workflow creates a cart.
+ */
 export const createCartWorkflow = createWorkflow(
   createCartWorkflowId,
   (input: WorkflowData<CreateCartWorkflowInputDTO & AdditionalData>) => {

packages/core/core-flows/src/definition/cart/workflows/create-payment-collection-for-cart.ts

@@ -24,6 +24,9 @@ const validateExistingPaymentCollection = createStep(
 
 export const createPaymentCollectionForCartWorkflowId =
   "create-payment-collection-for-cart"
+/**
+ * This workflow creates a payment collection for a cart.
+ */
 export const createPaymentCollectionForCartWorkflow = createWorkflow(
   createPaymentCollectionForCartWorkflowId,
   (

packages/core/core-flows/src/definition/cart/workflows/list-shipping-options-for-cart.ts

@@ -10,6 +10,9 @@ import { useRemoteQueryStep } from "../../../common/steps/use-remote-query"
 
 export const listShippingOptionsForCartWorkflowId =
   "list-shipping-options-for-cart"
+/**
+ * This workflow lists the shipping options of a cart.
+ */
 export const listShippingOptionsForCartWorkflow = createWorkflow(
   listShippingOptionsForCartWorkflowId,
   (input: WorkflowData<ListShippingOptionsForCartWorkflowInputDTO>) => {

packages/core/core-flows/src/definition/cart/workflows/refresh-payment-collection.ts

@@ -10,15 +10,18 @@ import { useRemoteQueryStep } from "../../../common/steps/use-remote-query"
 import { updatePaymentCollectionStep } from "../../../payment-collection"
 import { deletePaymentSessionsWorkflow } from "../../../payment-collection/workflows/delete-payment-sessions"
 
-type WorklowInput = {
+export type RefreshPaymentCollectionForCartWorklowInput = {
   cart_id: string
 }
 
 export const refreshPaymentCollectionForCartWorkflowId =
   "refresh-payment-collection-for-cart"
+/**
+ * This workflow refreshes the payment collections of a cart.
+ */
 export const refreshPaymentCollectionForCartWorkflow = createWorkflow(
   refreshPaymentCollectionForCartWorkflowId,
-  (input: WorkflowData<WorklowInput>): WorkflowData<void> => {
+  (input: WorkflowData<RefreshPaymentCollectionForCartWorklowInput>): WorkflowData<void> => {
     const cart = useRemoteQueryStep({
       entry_point: "cart",
       fields: [

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

@@ -17,7 +17,7 @@ import {
 import { updateCartPromotionsStep } from "../steps/update-cart-promotions"
 import { cartFieldsForRefreshSteps } from "../utils/fields"
 
-type WorkflowInput = {
+export type UpdateCartPromotionsWorkflowInput = {
   promoCodes: string[]
   cartId: string
   action?:
@@ -27,9 +27,12 @@ type WorkflowInput = {
 }
 
 export const updateCartPromotionsWorkflowId = "update-cart-promotions"
+/**
+ * This workflow updates a cart's promotions.
+ */
 export const updateCartPromotionsWorkflow = createWorkflow(
   updateCartPromotionsWorkflowId,
-  (input: WorkflowData<WorkflowInput>): WorkflowData<void> => {
+  (input: WorkflowData<UpdateCartPromotionsWorkflowInput>): WorkflowData<void> => {
     const cart = useRemoteQueryStep({
       entry_point: "cart",
       fields: cartFieldsForRefreshSteps,

packages/core/core-flows/src/definition/cart/workflows/update-cart.ts

@@ -22,6 +22,9 @@ import { cartFieldsForRefreshSteps } from "../utils/fields"
 import { refreshPaymentCollectionForCartWorkflow } from "./refresh-payment-collection"
 
 export const updateCartWorkflowId = "update-cart"
+/**
+ * This workflow updates a cart.
+ */
 export const updateCartWorkflow = createWorkflow(
   updateCartWorkflowId,
   (input: WorkflowData<UpdateCartWorkflowInputDTO & AdditionalData>) => {

packages/core/core-flows/src/definition/cart/workflows/update-line-item-in-cart.ts

@@ -21,6 +21,9 @@ import { refreshPaymentCollectionForCartWorkflow } from "./refresh-payment-colle
 // - Validate shipping methods for new items (fulfillment module)
 
 export const updateLineItemInCartWorkflowId = "update-line-item-in-cart"
+/**
+ * This workflow updates a cart's line item.
+ */
 export const updateLineItemInCartWorkflow = createWorkflow(
   updateLineItemInCartWorkflowId,
   (input: WorkflowData<UpdateLineItemInCartWorkflowInputDTO>) => {

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

@@ -60,7 +60,7 @@ const cartFields = [
   "shipping_address.province",
 ]
 
-type WorkflowInput = {
+export type UpdateTaxLinesWorkflowInput = {
   cart_or_cart_id: string | CartWorkflowDTO
   items?: CartLineItemDTO[]
   shipping_methods?: CartShippingMethodDTO[]
@@ -68,9 +68,12 @@ type WorkflowInput = {
 }
 
 export const updateTaxLinesWorkflowId = "update-tax-lines"
+/**
+ * This workflow updates a cart's tax lines.
+ */
 export const updateTaxLinesWorkflow = createWorkflow(
   updateTaxLinesWorkflowId,
-  (input: WorkflowData<WorkflowInput>): WorkflowData<void> => {
+  (input: WorkflowData<UpdateTaxLinesWorkflowInput>): WorkflowData<void> => {
     const cart = retrieveCartWithLinksStep({
       cart_or_cart_id: input.cart_or_cart_id,
       fields: cartFields,