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

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

@@ -48,7 +48,7 @@ export const createCartWorkflowId = "create-cart"
  * 
  * This workflow has a hook that allows you to perform custom actions on the created cart. You can see an example in [this guide](https://docs.medusajs.com/resources/commerce-modules/cart/extend#step-4-consume-cartcreated-workflow-hook).
  * 
- * You can also use this workflow within your own custom workflows, allowing you to wrap custom logic around cart creation.
+ * You can also use this workflow within your customizations or your own custom workflows, allowing you to wrap custom logic around cart creation.
  * 
  * @example
  * const { result } = await createCartWorkflow(container)

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

@@ -48,7 +48,7 @@ export const updateCartWorkflowId = "update-cart"
  * This workflow has a hook that allows you to perform custom actions on the updated cart. For example, you can pass custom data under the `additional_data` property of the Update Cart API route, 
  * then update any associated details related to the cart in the workflow's hook.
  * 
- * You can also use this workflow within your own custom workflows, allowing you to wrap custom logic around updating a cart.
+ * You can also use this workflow within your customizations or your own custom workflows, allowing you to wrap custom logic around updating a cart.
  * 
  * @example
  * const { result } = await updateCartWorkflow(container)

packages/core/core-flows/src/customer/workflows/create-addresses.ts

@@ -33,7 +33,7 @@ export const createCustomerAddressesWorkflowId = "create-customer-addresses"
  * This workflow has a hook that allows you to perform custom actions on the created customer addresses. For example, you can pass under `additional_data` custom data that
  * allows you to create custom data models linked to the addresses.
  * 
- * You can also use this workflow within your own custom workflows, allowing you to wrap custom logic around creating customer addresses.
+ * You can also use this workflow within your customizations or your own custom workflows, allowing you to wrap custom logic around creating customer addresses.
  * 
  * @example
  * const { result } = await createCustomerAddressesWorkflow(container)

packages/core/core-flows/src/customer/workflows/create-customers.ts

@@ -25,7 +25,7 @@ export const createCustomersWorkflowId = "create-customers"
  * 
  * This workflow has a hook that allows you to perform custom actions on the created customer. You can see an example in [this guide](https://docs.medusajs.com/resources/commerce-modules/customer/extend).
  * 
- * You can also use this workflow within your own custom workflows, allowing you to wrap custom logic around creating customers.
+ * You can also use this workflow within your customizations or your own custom workflows, allowing you to wrap custom logic around creating customers.
  * 
  * @example
  * const { result } = await createCustomersWorkflow(container)

packages/core/core-flows/src/customer/workflows/update-addresses.ts

@@ -38,7 +38,7 @@ export const updateCustomerAddressesWorkflowId = "update-customer-addresses"
  * This workflow has a hook that allows you to perform custom actions on the updated customer addresses. For example, you can pass under `additional_data` custom data that
  * allows you to update custom data models linked to the addresses.
  * 
- * You can also use this workflow within your own custom workflows, allowing you to wrap custom logic around updating customer addresses.
+ * You can also use this workflow within your customizations or your own custom workflows, allowing you to wrap custom logic around updating customer addresses.
  * 
  * @example
  * const { result } = await updateCustomerAddressesWorkflow(container)

packages/core/core-flows/src/customer/workflows/update-customers.ts

@@ -36,7 +36,7 @@ export const updateCustomersWorkflowId = "update-customers"
  * This workflow has a hook that allows you to perform custom actions on the updated customer. For example, you can pass under `additional_data` custom data to update
  * custom data models linked to the customers.
  * 
- * You can also use this workflow within your own custom workflows, allowing you to wrap custom logic around updating customers.
+ * You can also use this workflow within your customizations or your own custom workflows, allowing you to wrap custom logic around updating customers.
  * 
  * @example
  * const { result } = await updateCustomersWorkflow(container)

packages/core/core-flows/src/order/steps/add-order-transaction.ts

@@ -2,14 +2,24 @@ import { CreateOrderTransactionDTO } from "@medusajs/framework/types"
 import { Modules } from "@medusajs/framework/utils"
 import { StepResponse, createStep } from "@medusajs/framework/workflows-sdk"
 
+/**
+ * The transaction(s) to add to the order.
+ */
+export type AddOrderTransactionStepInput = CreateOrderTransactionDTO | CreateOrderTransactionDTO[]
+
+/**
+ * The added order transaction(s).
+ */
+export type AddOrderTransactionStepOutput = CreateOrderTransactionDTO | CreateOrderTransactionDTO[]
+
 export const addOrderTransactionStepId = "add-order-transaction"
 /**
  * This step creates order transactions.
  */
 export const addOrderTransactionStep = createStep(
   addOrderTransactionStepId,
   async (
-    data: CreateOrderTransactionDTO | CreateOrderTransactionDTO[],
+    data: AddOrderTransactionStepInput,
     { container }
   ) => {
     const service = container.resolve(Modules.ORDER)
@@ -36,7 +46,7 @@ export const addOrderTransactionStep = createStep(
     const created = await service.addOrderTransactions(trxsData)
 
     return new StepResponse(
-      Array.isArray(data) ? created : created[0],
+      (Array.isArray(data) ? created : created[0]) as AddOrderTransactionStepOutput,
       created.map((c) => c.id)
     )
   },

packages/core/core-flows/src/order/steps/archive-orders.ts

@@ -2,7 +2,13 @@ import { IOrderModuleService } from "@medusajs/framework/types"
 import { Modules } from "@medusajs/framework/utils"
 import { createStep, StepResponse } from "@medusajs/framework/workflows-sdk"
 
+/**
+ * The details of archiving the orders.
+ */
 export type ArchiveOrdersStepInput = {
+  /**
+   * The IDs of the orders to archive.
+   */
   orderIds: string[]
 }
 

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

@@ -8,6 +8,17 @@ import { StepResponse, createStep } from "@medusajs/framework/workflows-sdk"
 export const cancelOrderFulfillmentStepId = "cancel-order-fulfillment"
 /**
  * This step cancels an order's fulfillment.
+ * 
+ * @example
+ * const data = cancelOrderFulfillmentStep({
+ *   order_id: "order_123",
+ *   items: [
+ *     {
+ *       id: "item_123",
+ *       quantity: 1
+ *     }
+ *   ]
+ * })
  */
 export const cancelOrderFulfillmentStep = createStep(
   cancelOrderFulfillmentStepId,

packages/core/core-flows/src/order/steps/cancel-orders.ts

@@ -2,8 +2,17 @@ import { IOrderModuleService } from "@medusajs/framework/types"
 import { Modules } from "@medusajs/framework/utils"
 import { createStep, StepResponse } from "@medusajs/framework/workflows-sdk"
 
+/**
+ * The details of canceling the orders.
+ */
 export type CancelOrdersStepInput = {
+  /**
+   * The IDs of the orders to cancel.
+   */
   orderIds: string[]
+  /**
+   * The ID of the user canceling the orders.
+   */
   canceled_by?: string
 }
 

packages/core/core-flows/src/order/steps/claim/create-claim-items-from-actions.ts

@@ -5,13 +5,40 @@ import {
 import { ChangeActionType, Modules } from "@medusajs/framework/utils"
 import { StepResponse, createStep } from "@medusajs/framework/workflows-sdk"
 
+/**
+ * The details of creating the claim items from a change action.
+ */
 export type CreateOrderClaimItemsFromActionsInput = {
+  /**
+   * The change actions to create claim items from.
+   */
   changes: OrderChangeActionDTO[]
+  /**
+   * The ID of the claim to create the items for.
+   */
   claimId: string
 }
 
 /**
  * This step creates claim items from a change action.
+ * 
+ * :::note
+ * 
+ * You can retrieve an order change action details using [Query](https://docs.medusajs.com/learn/fundamentals/module-links/query),
+ * or [useQueryGraphStep](https://docs.medusajs.com/resources/references/medusa-workflows/steps/useQueryGraphStep).
+ * 
+ * :::
+ * 
+ * @example
+ * const data = createOrderClaimItemsFromActionsStep({
+ *   claimId: "claim_123",
+ *   changes: [
+ *     {
+ *       id: "orchact_123",
+ *       // other order change action details...
+ *     }
+ *   ]
+ * })
  */
 export const createOrderClaimItemsFromActionsStep = createStep(
   "create-claim-items-from-change-actions",

packages/core/core-flows/src/order/steps/claim/delete-claims.ts

@@ -2,13 +2,23 @@ import { IOrderModuleService } from "@medusajs/framework/types"
 import { Modules } from "@medusajs/framework/utils"
 import { createStep, StepResponse } from "@medusajs/framework/workflows-sdk"
 
+/**
+ * The details of deleting one or more claims.
+ */
+export type DeleteOrderClaimsInput = {
+  /**
+   * The IDs of the claims to delete.
+   */
+  ids: string[]
+}
+
 export const deleteClaimsStepId = "delete-claims"
 /**
  * This step deletes one or more order claims.
  */
 export const deleteClaimsStep = createStep(
   deleteClaimsStepId,
-  async (data: { ids: string[] }, { container }) => {
+  async (data: DeleteOrderClaimsInput, { container }) => {
     const service = container.resolve<IOrderModuleService>(Modules.ORDER)
 
     const deleted = await service.softDeleteOrderClaims(data.ids)

packages/core/core-flows/src/order/steps/complete-orders.ts

@@ -2,7 +2,13 @@ import { IOrderModuleService } from "@medusajs/framework/types"
 import { Modules } from "@medusajs/framework/utils"
 import { createStep, StepResponse } from "@medusajs/framework/workflows-sdk"
 
+/**
+ * The details of completing the orders.
+ */
 export type CompleteOrdersStepInput = {
+  /**
+   * The IDs of the orders to complete.
+   */
   orderIds: string[]
 }
 

packages/core/core-flows/src/order/steps/confirm-order-changes.ts

@@ -2,9 +2,21 @@ import { OrderChangeDTO } from "@medusajs/framework/types"
 import { Modules } from "@medusajs/framework/utils"
 import { createStep, StepResponse } from "@medusajs/framework/workflows-sdk"
 
+/**
+ * The input for the confirm order changes step.
+ */
 export type ConfirmOrderChangesInput = {
+  /**
+   * The ID of the order to confirm changes for.
+   */
   orderId: string
+  /**
+   * The changes to confirm.
+   */
   changes: OrderChangeDTO[]
+  /**
+   * The ID of the user confirming the changes.
+   */
   confirmed_by?: string
 }
 

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

@@ -2,13 +2,32 @@ import { CreateOrderLineItemDTO } from "@medusajs/framework/types"
 import { Modules } from "@medusajs/framework/utils"
 import { StepResponse, createStep } from "@medusajs/framework/workflows-sdk"
 
+/**
+ * The details of creating order line items.
+ */
 export interface CreateOrderLineItemsStepInput {
+  /**
+   * The items to create.
+   */
   items: CreateOrderLineItemDTO[]
 }
 
 export const createOrderLineItemsStepId = "create-order-line-items-step"
 /**
  * This step creates order line items.
+ * 
+ * @example
+ * const data = createOrderLineItemsStep({
+ *   items: [
+ *     {
+ *       variant_id: "variant_123",
+ *       quantity: 1,
+ *       unit_price: 10,
+ *       title: "Shirt",
+ *       order_id: "order_123"
+ *     }
+ *   ]
+ * })
  */
 export const createOrderLineItemsStep = createStep(
   createOrderLineItemsStepId,

packages/core/core-flows/src/order/steps/create-order-shipping-methods.ts

@@ -5,7 +5,13 @@ import {
 import { Modules } from "@medusajs/framework/utils"
 import { StepResponse, createStep } from "@medusajs/framework/workflows-sdk"
 
+/**
+ * The details of creating order shipping methods.
+ */
 export interface CreateOrderShippingMethodsStepInput {
+  /**
+   * The shipping methods to create.
+   */
   shipping_methods: CreateOrderShippingMethodDTO[]
 }
 

packages/core/core-flows/src/order/steps/create-orders.ts

@@ -2,9 +2,28 @@ import { CreateOrderDTO, IOrderModuleService } from "@medusajs/framework/types"
 import { Modules } from "@medusajs/framework/utils"
 import { StepResponse, createStep } from "@medusajs/framework/workflows-sdk"
 
+/**
+ * The orders to create.
+ */
+export type CreateOrdersStepInput = CreateOrderDTO[]
+
 export const createOrdersStepId = "create-orders"
 /**
  * This step creates one or more orders.
+ * 
+ * @example
+ * const data = createOrdersStep([{
+ *   region_id: "region_123",
+ *   customer_id: "customer_123",
+ *   items: [
+ *     {
+ *       variant_id: "variant_123",
+ *       quantity: 1,
+ *       title: "Shirt",
+ *       unit_price: 10,
+ *     }
+ *   ]
+ * }])
  */
 export const createOrdersStep = createStep(
   createOrdersStepId,

packages/core/core-flows/src/order/steps/delete-line-items.ts

@@ -2,7 +2,13 @@ import { IOrderModuleService } from "@medusajs/framework/types"
 import { Modules } from "@medusajs/framework/utils"
 import { StepResponse, createStep } from "@medusajs/framework/workflows-sdk"
 
+/**
+ * The details of deleting order line items.
+ */
 export interface DeleteOrderLineItemsStepInput {
+  /**
+   * The IDs of the order line items to delete.
+   */
   ids: string[]
 }
 

packages/core/core-flows/src/order/steps/delete-order-change-actions.ts

@@ -2,13 +2,23 @@ import { IOrderModuleService } from "@medusajs/framework/types"
 import { Modules } from "@medusajs/framework/utils"
 import { StepResponse, createStep } from "@medusajs/framework/workflows-sdk"
 
+/**
+ * The details of deleting order change actions.
+ */
+export interface DeleteOrderChangeActionsStepInput {
+  /**
+   * The IDs of the order change actions to delete.
+   */
+  ids: string[]
+}
+
 export const deleteOrderChangeActionsStepId = "delete-order-change-actions"
 /**
  * This step deletes order change actions.
  */
 export const deleteOrderChangeActionsStep = createStep(
   deleteOrderChangeActionsStepId,
-  async (data: { ids: string[] }, { container }) => {
+  async (data: DeleteOrderChangeActionsStepInput, { container }) => {
     const service = container.resolve<IOrderModuleService>(Modules.ORDER)
 
     await service.softDeleteOrderChangeActions(data.ids)

packages/core/core-flows/src/order/steps/delete-order-changes.ts

@@ -2,13 +2,23 @@ import { IOrderModuleService } from "@medusajs/framework/types"
 import { Modules } from "@medusajs/framework/utils"
 import { createStep, StepResponse } from "@medusajs/framework/workflows-sdk"
 
+/**
+ * The details of deleting order changes.
+ */
+export interface DeleteOrderChangesStepInput {
+  /**
+   * The IDs of the order changes to delete.
+   */
+  ids: string[]
+}
+
 export const deleteOrderChangesStepId = "delete-order-change"
 /**
  * This step deletes order changes.
  */
 export const deleteOrderChangesStep = createStep(
   deleteOrderChangesStepId,
-  async (data: { ids: string[] }, { container }) => {
+  async (data: DeleteOrderChangesStepInput, { container }) => {
     const service = container.resolve<IOrderModuleService>(Modules.ORDER)
 
     const deleted = await service.softDeleteOrderChanges(data.ids)

packages/core/core-flows/src/order/steps/delete-order-shipping-methods.ts

@@ -2,7 +2,13 @@ import { IOrderModuleService } from "@medusajs/framework/types"
 import { Modules } from "@medusajs/framework/utils"
 import { StepResponse, createStep } from "@medusajs/framework/workflows-sdk"
 
+/**
+ * The details of deleting order shipping methods.
+ */
 export interface DeleteOrderShippingMethodsStepInput {
+  /**
+   * The IDs of the order shipping methods to delete.
+   */
   ids: string[]
 }