chore(core-flows,types): improve tsdocs of workflows [1] (#10940)

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

@@ -37,7 +37,7 @@ import { updateCartPromotionsWorkflow } from "./update-cart-promotions"
 import { updateTaxLinesWorkflow } from "./update-tax-lines"
 
 /**
- * The data to create the cart, along with custom data that's later passed to the cart's hooks.
+ * The data to create the cart, along with custom data that's passed to the workflow's hooks.
  */
 export type CreateCartWorkflowInput = CreateCartWorkflowInputDTO & AdditionalData
 
@@ -61,13 +61,18 @@ export const createCartWorkflowId = "create-cart"
  *           quantity: 1,
  *         }
  *       ],
- *       customer_id: "cus_123"
+ *       customer_id: "cus_123",
+ *       additional_data: {
+ *         external_id: "123"
+ *       }
  *     }
  *   })
  * 
  * @summary
  * 
  * Create a cart specifying region, items, and more.
+ * 
+ * @property hooks.cartCreated - This hook is executed after a cart is created. You can consume this hook to perform custom actions on the created cart.
  */
 export const createCartWorkflow = createWorkflow(
   createCartWorkflowId,
@@ -229,10 +234,6 @@ export const createCartWorkflow = createWorkflow(
       })
     )
 
-    /**
-     * This hook is executed after a cart is created. You can consume this hook to perform
-     * custom actions on the created cart.
-     */
     const cartCreated = createHook("cartCreated", {
       cart,
       additional_data: input.additional_data,

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

@@ -29,13 +29,57 @@ import {
 } from "../steps"
 import { refreshCartItemsWorkflow } from "./refresh-cart-items"
 
+/**
+ * The data to update the cart, along with custom data that's passed to the workflow's hooks.
+ */
+export type UpdateCartWorkflowInput = UpdateCartWorkflowInputDTO & AdditionalData
+
 export const updateCartWorkflowId = "update-cart"
 /**
- * This workflow updates a cart.
+ * This workflow updates a cart and returns it. You can update the cart's region, address, and more. This workflow is executed by the 
+ * [Update Cart Store API Route](https://docs.medusajs.com/api/store#carts_postcartsid).
+ * 
+ * :::note
+ * 
+ * This workflow doesn't allow updating a cart's line items. Instead, use {@link addToCartWorkflow} and {@link updateLineItemInCartWorkflow}.
+ * 
+ * :::
+ * 
+ * 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.
+ * 
+ * @example
+ * const { result } = await updateCartWorkflow(container)
+ * .run({
+ *   input: {
+ *     id: "cart_123",
+ *     region_id: "region_123",
+ *     shipping_address: {
+ *       first_name: "John",
+ *       last_name: "Doe",
+ *       address_1: "1234 Main St",
+ *       city: "San Francisco",
+ *       country_code: "US",
+ *       postal_code: "94111",
+ *       phone: "1234567890",
+ *     },
+ *     additional_data: {
+ *       external_id: "123"
+ *     }
+ *   }
+ * })
+ * 
+ * @summary
+ * 
+ * Update a cart's details, such as region, address, and more.
+ * 
+ * @property hooks.cartUpdated - This hook is executed after a cart is update. You can consume this hook to perform custom actions on the updated cart.
  */
 export const updateCartWorkflow = createWorkflow(
   updateCartWorkflowId,
-  (input: WorkflowData<UpdateCartWorkflowInputDTO & AdditionalData>) => {
+  (input: WorkflowData<UpdateCartWorkflowInput>) => {
     const cartToUpdate = useRemoteQueryStep({
       entry_point: "cart",
       variables: { id: input.id },

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

@@ -3,7 +3,6 @@ import {
   CreateCustomerAddressDTO,
 } from "@medusajs/framework/types"
 import {
-  WorkflowData,
   WorkflowResponse,
   createHook,
   createWorkflow,
@@ -16,17 +15,65 @@ import {
   maybeUnsetDefaultShippingAddressesStep,
 } from "../steps"
 
+/**
+ * The data to create one or more customer addresses, along with custom data that's passed to the workflow's hooks.
+ */
 export type CreateCustomerAddressesWorkflowInput = {
+  /**
+   * The addresses to create.
+   */
   addresses: CreateCustomerAddressDTO[]
 } & AdditionalData
 
 export const createCustomerAddressesWorkflowId = "create-customer-addresses"
 /**
- * This workflow creates one or more customer address.
+ * This workflow creates one or more addresses for customers. It's used by the [Add Customer Address Admin API Route](https://docs.medusajs.com/api/admin#customers_postcustomersidaddresses)
+ * and the [Add Customer Address Store API Route](https://docs.medusajs.com/api/store#customers_postcustomersmeaddresses).
+ * 
+ * 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.
+ * 
+ * @example
+ * const { result } = await createCustomerAddressesWorkflow(container)
+ * .run({
+ *   input: {
+ *     addresses: [
+ *       {
+ *         customer_id: "cus_123",
+ *         address_1: "456 Elm St",
+ *         city: "Los Angeles",
+ *         country_code: "us",
+ *         postal_code: "90001",
+ *         first_name: "Jane",
+ *         last_name: "Smith",
+ *       },
+ *       {
+ *         customer_id: "cus_321",
+ *         address_1: "789 Oak St",
+ *         city: "New York",
+ *         country_code: "us",
+ *         postal_code: "10001",
+ *         first_name: "Alice",
+ *         last_name: "Johnson",
+ *       }
+ *     ],
+ *     additional_data: {
+ *       crm_id: "123"
+ *     }
+ *   }
+ * })
+ * 
+ * @summary
+ * 
+ * Create one or more customer addresses.
+ * 
+ * @property hooks.addressesCreated - This hook is executed after the addresses are created. You can consume this hook to perform custom actions on the created addresses.
  */
 export const createCustomerAddressesWorkflow = createWorkflow(
   createCustomerAddressesWorkflowId,
-  (input: WorkflowData<CreateCustomerAddressesWorkflowInput>) => {
+  (input: CreateCustomerAddressesWorkflowInput) => {
     const unsetInput = transform(input, (data) => ({
       create: data.addresses,
     }))

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

@@ -1,7 +1,6 @@
 import { AdditionalData, CreateCustomerDTO } from "@medusajs/framework/types"
 import { CustomerWorkflowEvents } from "@medusajs/framework/utils"
 import {
-  WorkflowData,
   WorkflowResponse,
   createHook,
   createWorkflow,
@@ -10,17 +9,50 @@ import {
 import { emitEventStep } from "../../common/steps/emit-event"
 import { createCustomersStep } from "../steps"
 
+/**
+ * The data to create one or more customers, along with custom data that's passed to the workflow's hooks.
+ */
 export type CreateCustomersWorkflowInput = {
+  /**
+   * The customers to create.
+   */
   customersData: CreateCustomerDTO[]
 } & AdditionalData
 
 export const createCustomersWorkflowId = "create-customers"
 /**
- * This workflow creates one or more customers.
+ * This workflow creates one or more customers. It's used by the [Create Customer Admin API Route](https://docs.medusajs.com/api/admin#customers_postcustomers).
+ * 
+ * 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.
+ * 
+ * @example
+ * const { result } = await createCustomersWorkflow(container)
+ * .run({
+ *   input: {
+ *     customersData: [
+ *       {
+ *         first_name: "John",
+ *         last_name: "Doe",
+ *         email: "john.doe@example.com",
+ *       },
+ *     ],
+ *     additional_data: {
+ *       position_name: "Editor",
+ *     }
+ *   }
+ * })
+ * 
+ * @summary
+ * 
+ * Create one or more customers.
+ * 
+ * @property hooks.customersCreated - This hook is executed after the customers are created. You can consume this hook to perform custom actions on the created customers.
  */
 export const createCustomersWorkflow = createWorkflow(
   createCustomersWorkflowId,
-  (input: WorkflowData<CreateCustomersWorkflowInput>) => {
+  (input: CreateCustomersWorkflowInput) => {
     const createdCustomers = createCustomersStep(input.customersData)
     const customersCreated = createHook("customersCreated", {
       customers: createdCustomers,

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

@@ -4,7 +4,6 @@ import {
   AdditionalData,
 } from "@medusajs/framework/types"
 import {
-  WorkflowData,
   WorkflowResponse,
   createHook,
   createWorkflow,
@@ -17,18 +16,55 @@ import {
   updateCustomerAddressesStep,
 } from "../steps"
 
+/**
+ * The data to update one or more customer addresses, along with custom data that's passed to the workflow's hooks.
+ */
 export type UpdateCustomerAddressesWorkflowInput = {
+  /**
+   * The filters to select the addresses to update.
+   */
   selector: FilterableCustomerAddressProps
+  /**
+   * The data to update in the addresses.
+   */
   update: UpdateCustomerAddressDTO
 } & AdditionalData
 
 export const updateCustomerAddressesWorkflowId = "update-customer-addresses"
 /**
- * This workflow updates one or more customer addresses.
+ * This workflow updates one or more addresses for customers. It's used by the [Update Customer Address Admin API Route](https://docs.medusajs.com/api/admin#customers_postcustomersidaddressesaddress_id)
+ * and the [Update Customer Address Store API Route](https://docs.medusajs.com/api/store#customers_postcustomersmeaddressesaddress_id).
+ * 
+ * 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.
+ * 
+ * @example
+ * const { result } = await updateCustomerAddressesWorkflow(container)
+ * .run({
+ *   input: {
+ *     selector: {
+ *       customer_id: "123"
+ *     },
+ *     update: {
+ *       first_name: "John"
+ *     },
+ *     additional_data: {
+ *       crm_id: "123"
+ *     }
+ *   }
+ * })
+ * 
+ * @summary
+ * 
+ * Update one or more customer addresses.
+ * 
+ * @property hooks.addressesUpdated - This hook is executed after the addresses are updated. You can consume this hook to perform custom actions on the updated addresses.
  */
 export const updateCustomerAddressesWorkflow = createWorkflow(
   updateCustomerAddressesWorkflowId,
-  (input: WorkflowData<UpdateCustomerAddressesWorkflowInput>) => {
+  (input: UpdateCustomerAddressesWorkflowInput) => {
     const unsetInput = transform(input, (data) => ({
       update: data,
     }))

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

@@ -14,14 +14,48 @@ import {
 import { emitEventStep } from "../../common/steps/emit-event"
 import { updateCustomersStep } from "../steps"
 
+/**
+ * The data to update one or more customers, along with custom data that's passed to the workflow's hooks.
+ */
 export type UpdateCustomersWorkflowInput = {
+  /**
+   * The filters to select the customers to update.
+   */
   selector: FilterableCustomerProps
+  /**
+   * The data to update in the customers.
+   */
   update: CustomerUpdatableFields
 } & AdditionalData
 
 export const updateCustomersWorkflowId = "update-customers"
 /**
- * This workflow updates one or more customers.
+ * This workflow updates one or more customers. It's used by the [Update Customer Admin API Route](https://docs.medusajs.com/api/admin#customers_postcustomersid) and
+ * the [Update Customer Store API Route](https://docs.medusajs.com/api/store#customers_postcustomersme).
+ * 
+ * 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.
+ * 
+ * @example
+ * const { result } = await updateCustomersWorkflow(container)
+ * .run({
+ *   input: {
+ *     selector: {
+ *       id: ["cus_123"]
+ *     },
+ *     update: {
+ *       first_name: "John"
+ *     }
+ *   }
+ * })
+ * 
+ * @summary
+ * 
+ * Update one or more customers.
+ * 
+ * @property hooks.customersUpdated - This hook is executed after the customers are updated. You can consume this hook to perform custom actions on the updated customers.
  */
 export const updateCustomersWorkflow = createWorkflow(
   updateCustomersWorkflowId,

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

@@ -115,16 +115,42 @@ function prepareInventoryUpdate({
   }
 }
 
+/**
+ * The data to cancel an order's fulfillment, along with custom data that's passed to the workflow's hooks.
+ */
+export type CancelOrderFulfillmentWorkflowInput = OrderWorkflow.CancelOrderFulfillmentWorkflowInput & AdditionalData
+
 export const cancelOrderFulfillmentWorkflowId = "cancel-order-fulfillment"
 /**
- * This workflow cancels an order's fulfillment.
+ * This workflow cancels an order's fulfillment. It's used by the [Cancel Order's Fulfillment Admin API Route](https://docs.medusajs.com/api/admin#orders_postordersidfulfillmentsfulfillment_idcancel).
+ * 
+ * This workflow has a hook that allows you to perform custom actions on the canceled fulfillment. For example, you can pass under `additional_data` custom data that 
+ * allows you to update custom data models linked to the fulfillment.
+ * 
+ * You can also use this workflow within your own custom workflows, allowing you to wrap custom logic around canceling a fulfillment.
+ * 
+ * @example
+ * const { result } = await cancelOrderFulfillmentWorkflow(container)
+ * .run({
+ *   input: {
+ *     order_id: "order_123",
+ *     fulfillment_id: "ful_123",
+ *     additional_data: {
+ *       reason: "Customer changed their mind"
+ *     }
+ *   }
+ * })
+ * 
+ * @summary
+ * 
+ * Cancel an order's fulfillment.
+ * 
+ * @property hooks.orderFulfillmentCanceled - This hook is executed after the fulfillment is canceled. You can consume this hook to perform custom actions on the canceled fulfillment.
  */
 export const cancelOrderFulfillmentWorkflow = createWorkflow(
   cancelOrderFulfillmentWorkflowId,
   (
-    input: WorkflowData<
+    input: WorkflowData<CancelOrderFulfillmentWorkflowInput>
-      OrderWorkflow.CancelOrderFulfillmentWorkflowInput & AdditionalData
-    >
   ) => {
     const order: OrderDTO & { fulfillments: FulfillmentDTO[] } =
       useRemoteQueryStep({

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

@@ -10,13 +10,41 @@ import {
 import { emitEventStep } from "../../common/steps/emit-event"
 import { completeOrdersStep } from "../steps"
 
+/**
+ * The orders to complete, along with custom data that's passed to the workflow's hooks.
+ */
 export type CompleteOrdersWorkflowInput = {
+  /**
+   * The IDs of the orders to complete.
+   */
   orderIds: string[]
 } & AdditionalData
 
 export const completeOrderWorkflowId = "complete-order-workflow"
 /**
- * This workflow completes one or more orders.
+ * This workflow marks one or more orders as completed. It's used by the [Complete Cart Admin API Route](https://docs.medusajs.com/api/admin#orders_postordersidcomplete).
+ * 
+ * This workflow has a hook that allows you to perform custom actions on the completed orders. For example, you can pass under `additional_data` custom data that 
+ * allows you to update custom data models linked to the orders.
+ * 
+ * You can also use this workflow within your own custom workflows, allowing you to wrap custom logic around order completion.
+ * 
+ * @example
+ * const { result } = await completeOrderWorkflow(container)
+ * .run({
+ *   input: {
+ *     orderIds: ["order_1", "order_2"],
+ *     additional_data: {
+ *       send_webhook: true,
+ *     }
+ *   }
+ * })
+ * 
+ * @summary
+ * 
+ * Complete one or more orders.
+ * 
+ * @property hooks.ordersCompleted - This hook is executed after the orders are completed. You can consume this hook to perform custom actions on the completed orders.
  */
 export const completeOrderWorkflow = createWorkflow(
   completeOrderWorkflowId,

packages/core/core-flows/src/order/workflows/create-fulfillment.ts

@@ -14,7 +14,6 @@ import {
   OrderWorkflowEvents,
 } from "@medusajs/framework/utils"
 import {
-  WorkflowData,
   WorkflowResponse,
   createHook,
   createStep,
@@ -236,16 +235,47 @@ function prepareInventoryUpdate({
   }
 }
 
+/**
+ * The details of the fulfillment to create, along with custom data that's passed to the workflow's hooks.
+ */
+export type CreateOrderFulfillmentWorkflowInput = OrderWorkflow.CreateOrderFulfillmentWorkflowInput & AdditionalData
+
 export const createOrderFulfillmentWorkflowId = "create-order-fulfillment"
 /**
- * This creates a fulfillment for an order.
+ * This workflow creates a fulfillment for an order. It's used by the [Create Order Fulfillment Admin API Route](https://docs.medusajs.com/api/admin#orders_postordersidfulfillments).
+ * 
+ * This workflow has a hook that allows you to perform custom actions on the created fulfillment. For example, you can pass under `additional_data` custom data that 
+ * allows you to create custom data models linked to the fulfillment.
+ * 
+ * You can also use this workflow within your own custom workflows, allowing you to wrap custom logic around creating a fulfillment.
+ * 
+ * @example
+ * const { result } = await createOrderFulfillmentWorkflow(container)
+ * .run({
+ *   input: {
+ *     order_id: "order_123",
+ *     items: [
+ *       {
+ *         id: "orli_123",
+ *         quantity: 1,
+ *       }
+ *     ],
+ *     additional_data: {
+ *       send_oms: true
+ *     }
+ *   }
+ * })
+ * 
+ * @summary
+ * 
+ * Creates a fulfillment for an order.
+ * 
+ * @property hooks.fulfillmentCreated - This hook is executed after the fulfillment is created. You can consume this hook to perform custom actions on the created fulfillment.
  */
 export const createOrderFulfillmentWorkflow = createWorkflow(
   createOrderFulfillmentWorkflowId,
   (
-    input: WorkflowData<
+    input: CreateOrderFulfillmentWorkflowInput
-      OrderWorkflow.CreateOrderFulfillmentWorkflowInput & AdditionalData
-    >
   ) => {
     const order: OrderDTO = useRemoteQueryStep({
       entry_point: "orders",

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

@@ -1,7 +1,6 @@
 import { AdditionalData, CreateOrderDTO } from "@medusajs/framework/types"
 import { MedusaError, isDefined, isPresent } from "@medusajs/framework/utils"
 import {
-  WorkflowData,
   WorkflowResponse,
   createHook,
   createWorkflow,
@@ -77,13 +76,57 @@ function getOrderInput(data) {
   return data_
 }
 
+export type CreateOrderWorkflowInput = CreateOrderDTO & AdditionalData
+
 export const createOrdersWorkflowId = "create-orders"
 /**
- * This workflow creates an order.
+ * This workflow creates an order. It's used by the [Create Draft Order Admin API Route](https://docs.medusajs.com/api/admin#draft-orders_postdraftorders), but
+ * you can also use it to create any order.
+ * 
+ * This workflow has a hook that allows you to perform custom actions on the created order. For example, you can pass under `additional_data` custom data that 
+ * allows you to create custom data models linked to the order.
+ * 
+ * You can also use this workflow within your own custom workflows, allowing you to wrap custom logic around creating an order. For example,
+ * you can create a workflow that imports orders from an external system, then uses this workflow to create the orders in Medusa.
+ * 
+ * @example
+ * const { result } = await createOrderWorkflow(container)
+ * .run({
+ *   input: {
+ *     region_id: "reg_123",
+ *     items: [
+ *       {
+ *         variant_id: "variant_123",
+ *         quantity: 1,
+ *         title: "Shirt",
+ *         unit_price: 10
+ *       }
+ *     ],
+ *     sales_channel_id: "sc_123",
+ *     status: "pending",
+ *     shipping_address: {
+ *       first_name: "John",
+ *       last_name: "Doe",
+ *       address_1: "123 Main St",
+ *       city: "Los Angeles",
+ *       country_code: "us",
+ *       postal_code: "90001"
+ *     },
+ *     additional_data: {
+ *       sync_oms: true
+ *     }
+ *   }
+ * })
+ * 
+ * @summary
+ * 
+ * Create an order.
+ * 
+ * @property hooks.orderCreated - This hook is executed after the order is created. You can consume this hook to perform custom actions on the created order.
  */
 export const createOrderWorkflow = createWorkflow(
   createOrdersWorkflowId,
-  (input: WorkflowData<CreateOrderDTO & AdditionalData>) => {
+  (input: CreateOrderWorkflowInput) => {
     const variantIds = transform({ input }, (data) => {
       return (data.input.items ?? [])
         .map((item) => item.variant_id)

packages/core/core-flows/src/order/workflows/create-shipment.ts

@@ -6,7 +6,6 @@ import {
 } from "@medusajs/framework/types"
 import { FulfillmentEvents, Modules } from "@medusajs/framework/utils"
 import {
-  WorkflowData,
   WorkflowResponse,
   createHook,
   createStep,
@@ -76,16 +75,48 @@ function prepareRegisterShipmentData({
   }
 }
 
+/**
+ * The data to create a shipment for an order, along with custom data that's passed to the workflow's hooks.
+ */
+export type CreateOrderShipmentWorkflowInput = OrderWorkflow.CreateOrderShipmentWorkflowInput & AdditionalData
+
 export const createOrderShipmentWorkflowId = "create-order-shipment"
 /**
- * This workflow creates a shipment for an order.
+ * This workflow creates a shipment for an order. It's used by the [Create Order Shipment Admin API Route](https://docs.medusajs.com/api/admin#orders_postordersidfulfillmentsfulfillment_idshipments).
+ * 
+ * This workflow has a hook that allows you to perform custom actions on the created shipment. For example, you can pass under `additional_data` custom data that 
+ * allows you to create custom data models linked to the shipment.
+ * 
+ * You can also use this workflow within your own custom workflows, allowing you to wrap custom logic around creating a shipment.
+ * 
+ * @example
+ * const { result } = await createOrderShipmentWorkflow(container)
+ * .run({
+ *   input: {
+ *     order_id: "order_123",
+ *     fulfillment_id: "fulfillment_123",
+ *     items: [
+ *       {
+ *         id: "orli_123",
+ *         quantity: 1
+ *       }
+ *     ],
+ *     additional_data: {
+ *       oms_id: "123"
+ *     }
+ *   }
+ * })
+ * 
+ * @summary
+ * 
+ * Creates a shipment for an order.
+ * 
+ * @property hooks.shipmentCreated - This hook is executed after the shipment is created. You can consume this hook to perform custom actions on the created shipment.
  */
 export const createOrderShipmentWorkflow = createWorkflow(
   createOrderShipmentWorkflowId,
   (
-    input: WorkflowData<
+    input: CreateOrderShipmentWorkflowInput
-      OrderWorkflow.CreateOrderShipmentWorkflowInput & AdditionalData
-    >
   ) => {
     const order: OrderDTO = useRemoteQueryStep({
       entry_point: "orders",

packages/core/core-flows/src/product/workflows/create-product-options.ts

@@ -10,13 +10,50 @@ import {
 import { emitEventStep } from "../../common/steps/emit-event"
 import { createProductOptionsStep } from "../steps"
 
+/**
+ * The data to create one or more product options, along with custom data that's passed to the workflow's hooks.
+ */
 export type CreateProductOptionsWorkflowInput = {
+  /**
+   * The product options to create.
+   */
   product_options: ProductTypes.CreateProductOptionDTO[]
 } & AdditionalData
 
 export const createProductOptionsWorkflowId = "create-product-options"
 /**
- * This workflow creates one or more product options.
+ * This workflow creates one or more product options. It's used by the [Create Product Option Admin API Route](https://docs.medusajs.com/api/admin#products_postproductsidoptions).
+ * 
+ * This workflow has a hook that allows you to perform custom actions on the created product options. For example, you can pass under `additional_data` custom data that 
+ * allows you to create custom data models linked to the product options.
+ * 
+ * You can also use this workflow within your own custom workflows, allowing you to wrap custom logic around product-option creation.
+ * 
+ * @example
+ * const { result } = await createProductOptionsWorkflow(container)
+ * .run({
+ *   input: {
+ *     product_options: [
+ *       {
+ *         title: "Size",
+ *         values: ["S", "M", "L", "XL"]
+ *       },
+ *       {
+ *         title: "Color",
+ *         values: ["Red", "Blue", "Green"]
+ *       }
+ *     ],
+ *     additional_data: {
+ *       erp_id: "123"
+ *     }
+ *   }
+ * })
+ * 
+ * @summary
+ * 
+ * Create one or more product options.
+ * 
+ * @property hooks.productOptionsCreated - This hook is executed after the product options are created. You can consume this hook to perform custom actions on the created product options.
  */
 export const createProductOptionsWorkflow = createWorkflow(
   createProductOptionsWorkflowId,

packages/core/core-flows/src/product/workflows/create-product-variants.ts

@@ -26,15 +26,36 @@ import { createProductVariantsStep } from "../steps/create-product-variants"
 import { createVariantPricingLinkStep } from "../steps/create-variant-pricing-link"
 
 /**
+ * 
+ * The data to create one or more product variants, along with custom data that's passed to the workflow's hooks.
+ * 
  * @privateRemarks
  * TODO: Create separate typings for the workflow input
  */
 export type CreateProductVariantsWorkflowInput = {
+  /**
+   * The product variants to create.
+   */
   product_variants: (ProductTypes.CreateProductVariantDTO & {
+    /**
+     * The product variant's prices.
+     */
     prices?: PricingTypes.CreateMoneyAmountDTO[]
   } & {
+    /**
+     * The inventory items to associate with managed product variants.
+     */
     inventory_items?: {
+      /**
+       * The inventory item's ID.
+       */
       inventory_item_id: string
+      /**
+       * The number of units a single quantity is equivalent to. For example, if a customer orders one quantity of the variant, 
+       * Medusa checks the availability of the quantity multiplied by the value set for `required_quantity`. 
+       * When the customer orders the quantity, Medusa reserves the ordered quantity multiplied by the value 
+       * set for `required_quantity`.
+       */
       required_quantity?: number
     }[]
   })[]
@@ -179,7 +200,44 @@ const buildVariantItemCreateMap = (data: {
 
 export const createProductVariantsWorkflowId = "create-product-variants"
 /**
- * This workflow creates one or more product variants.
+ * This workflow creates one or more product variants. It's used by the [Create Product Variant Admin API Route](https://docs.medusajs.com/api/admin#products_postproductsidvariants).
+ * 
+ * This workflow has a hook that allows you to perform custom actions on the created product variants. For example, you can pass under `additional_data` custom data that 
+ * allows you to create custom data models linked to the product variants.
+ * 
+ * You can also use this workflow within your own custom workflows, allowing you to wrap custom logic around product-variant creation.
+ * 
+ * @example
+ * const { result } = await createProductVariantsWorkflow(container)
+ * .run({
+ *   input: {
+ *     product_variants: [
+ *       {
+ *         product_id: "prod_123",
+ *         sku: "SHIRT-123",
+ *         title: "Small Shirt",
+ *         prices: [
+ *           {
+ *             amount: 10,
+ *             currency_code: "USD",
+ *           },
+ *         ],
+ *         options: {
+ *           Size: "Small",
+ *         },
+ *       },
+ *     ],
+ *     additional_data: {
+ *       erp_id: "123"
+ *     }
+ *   }
+ * })
+ * 
+ * @summary
+ * 
+ * Create one or more product variants.
+ * 
+ * @property hooks.productVariantsCreated - This hook is executed after the product variants are created. You can consume this hook to perform custom actions on the created product variants.
  */
 export const createProductVariantsWorkflow = createWorkflow(
   createProductVariantsWorkflowId,

packages/core/core-flows/src/product/workflows/create-products.ts

@@ -30,7 +30,7 @@ const validateProductInputStepId = "validate-product-input"
 /**
  * This step validates a product data before creation.
  */
-const validateProductInputStep = createStep(
+export const validateProductInputStep = createStep(
   validateProductInputStepId,
   async (data: ValidateProductInputStepInput) => {
     const { products } = data
@@ -50,13 +50,67 @@ const validateProductInputStep = createStep(
   }
 )
 
+/**
+ * The data to create one or more products, along with custom data that's passed to the workflow's hooks.
+ */
 export type CreateProductsWorkflowInput = {
+  /**
+   * The products to create.
+   */
   products: CreateProductWorkflowInputDTO[]
 } & AdditionalData
 
 export const createProductsWorkflowId = "create-products"
 /**
- * This workflow creates one or more products.
+ * This workflow creates one or more products. It's used by the [Create Product Admin API Route](https://docs.medusajs.com/api/admin#products_postproducts).
+ * It can also be useful to you when creating [seed scripts](https://docs.medusajs.com/learn/fundamentals/custom-cli-scripts/seed-data), for example.
+ * 
+ * This workflow has a hook that allows you to perform custom actions on the created products. You can see an example in [this guide](https://docs.medusajs.com/resources/commerce-modules/product/extend).
+ * 
+ * You can also use this workflow within your own custom workflows, allowing you to wrap custom logic around product creation.
+ * 
+ * @example
+ * const { result } = await createProductsWorkflow(container)
+ * .run({
+ *   input: {
+ *     products: [
+ *       {
+ *         title: "Shirt",
+ *         options: [
+ *           {
+ *             title: "Size",
+ *             values: ["S", "M", "L"]
+ *           }
+ *         ],
+ *         variants: [
+ *           {
+ *             title: "Small Shirt",
+ *             sku: "SMALLSHIRT",
+ *             options: {
+ *               Size: "S"
+ *             },
+ *             prices: [
+ *               {
+ *                 amount: 10,
+ *                 currency_code: "usd"
+ *               }
+ *             ],
+ *             manage_inventory: true,
+ *           },
+ *         ]
+ *       }
+ *     ],
+ *     additional_data: {
+ *       erp_id: "123"
+ *     }
+ *   }
+ * })
+ * 
+ * @summary
+ * 
+ * Create one or more products with options and variants.
+ * 
+ * @property hooks.productCreated - This hook is executed after the products are created. You can consume this hook to perform custom actions on the created products.
  */
 export const createProductsWorkflow = createWorkflow(
   createProductsWorkflowId,

packages/core/core-flows/src/product/workflows/update-product-options.ts

@@ -10,14 +10,50 @@ import {
 import { emitEventStep } from "../../common/steps/emit-event"
 import { updateProductOptionsStep } from "../steps"
 
+/**
+ * The data to update one or more product options, along with custom data that's passed to the workflow's hooks.
+ */
 export type UpdateProductOptionsWorkflowInput = {
+  /**
+   * The filters to select the product options to update.
+   */
   selector: ProductTypes.FilterableProductOptionProps
+  /**
+   * The data to update in the product options.
+   */
   update: ProductTypes.UpdateProductOptionDTO
 } & AdditionalData
 
 export const updateProductOptionsWorkflowId = "update-product-options"
 /**
- * This workflow updates product options matching the specified filters.
+ * This workflow updates one or more product options. It's used by the [Update Product Option Admin API Route](https://docs.medusajs.com/api/admin#products_postproductsidvariantsvariant_id).
+ * 
+ * This workflow has a hook that allows you to perform custom actions on the updated product options. For example, you can pass under `additional_data` custom data that 
+ * allows you to update custom data models linked to the product options.
+ * 
+ * You can also use this workflow within your own custom workflows, allowing you to wrap custom logic around product-option update.
+ * 
+ * @example
+ * const { result } = await updateProductOptionsWorkflow(container)
+ * .run({
+ *   input: {
+ *     selector: {
+ *       title: "Color"
+ *     },
+ *     update: {
+ *       values: ["Red", "Blue", "Green"]
+ *     },
+ *     additional_data: {
+ *       erp_id: "123"
+ *     }
+ *   }
+ * })
+ * 
+ * @summary
+ * 
+ * Update one or more product options.
+ * 
+ * @property hooks.productOptionsUpdated - This hook is executed after the product options are updated. You can consume this hook to perform custom actions on the updated product options.
  */
 export const updateProductOptionsWorkflow = createWorkflow(
   updateProductOptionsWorkflowId,

packages/core/core-flows/src/product/workflows/update-product-variants.ts

@@ -16,27 +16,109 @@ import { updatePriceSetsStep } from "../../pricing"
 import { updateProductVariantsStep } from "../steps"
 import { getVariantPricingLinkStep } from "../steps/get-variant-pricing-link"
 
+/**
+ * The data to update one or more product variants, along with custom data that's passed to the workflow's hooks.
+ */
 export type UpdateProductVariantsWorkflowInput =
-  | {
+  (| {
+      /**
+       * A filter to select the product variants to update.
+       */
       selector: ProductTypes.FilterableProductVariantProps
+      /**
+       * The data to update in the product variants.
+       */
       update: ProductTypes.UpdateProductVariantDTO & {
+        /**
+         * The product variant's prices.
+         */
         prices?: Partial<PricingTypes.CreateMoneyAmountDTO>[]
       }
     }
   | {
+      /**
+       * The product variants to update.
+       */
       product_variants: (ProductTypes.UpsertProductVariantDTO & {
+        /**
+         * The product variant's prices.
+         */
         prices?: Partial<PricingTypes.CreateMoneyAmountDTO>[]
       })[]
-    }
+    }) & AdditionalData
 
 export const updateProductVariantsWorkflowId = "update-product-variants"
 /**
- * This workflow updates one or more product variants.
+ * This workflow updates one or more product variants. It's used by the [Update Product Variant Admin API Route](https://docs.medusajs.com/api/admin#products_postproductsidvariantsvariant_id).
+ * 
+ * This workflow has a hook that allows you to perform custom actions on the updated product variants. For example, you can pass under `additional_data` custom data that 
+ * allows you to update custom data models linked to the product variants.
+ * 
+ * You can also use this workflow within your own custom workflows, allowing you to wrap custom logic around product-variant update.
+ * 
+ * @example
+ * To update product variants by their IDs:
+ * 
+ * ```ts
+ * const { result } = await updateProductVariantsWorkflow(container)
+ * .run({
+ *   input: {
+ *     product_variants: [
+ *       {
+ *         id: "variant_123",
+ *         prices: [
+ *           {
+ *             amount: 10,
+ *             currency_code: "usd",
+ *           }
+ *         ]
+ *       },
+ *       {
+ *         id: "variant_321",
+ *         title: "Small Shirt",
+ *       },
+ *     ],
+ *     additional_data: {
+ *       erp_id: "123"
+ *     }
+ *   }
+ * })
+ * ```
+ * 
+ * You can also update product variants by a selector:
+ * 
+ * ```ts
+ * const { result } = await updateProductVariantsWorkflow(container)
+ * .run({
+ *   input: {
+ *     selector: {
+ *       product_id: "prod_123"
+ *     },
+ *     update: {
+ *       prices: [
+ *         {
+ *           amount: 10,
+ *           currency_code: "usd"
+ *         }
+ *       ]
+ *     },
+ *     additional_data: {
+ *       erp_id: "123"
+ *     }
+ *   }
+ * })
+ * ```
+ * 
+ * @summary
+ * 
+ * Update one or more product variants.
+ * 
+ * @property hooks.productVariantsUpdated - This hook is executed after the product variants are updated. You can consume this hook to perform custom actions on the updated product variants.
  */
 export const updateProductVariantsWorkflow = createWorkflow(
   updateProductVariantsWorkflowId,
   (
-    input: WorkflowData<UpdateProductVariantsWorkflowInput & AdditionalData>
+    input: WorkflowData<UpdateProductVariantsWorkflowInput>
   ) => {
     // Passing prices to the product module will fail, we want to keep them for after the variant is updated.
     const updateWithoutPrices = transform({ input }, (data) => {

packages/core/core-flows/src/product/workflows/update-products.ts

@@ -27,21 +27,51 @@ import {
 } from "../../common"
 import { upsertVariantPricesWorkflow } from "./upsert-variant-prices"
 
+/**
+ * Update products that match a specified selector, along with custom data that's passed to the workflow's hooks.
+ */
 export type UpdateProductsWorkflowInputSelector = {
+  /**
+   * The filters to find products to update.
+   */
   selector: ProductTypes.FilterableProductProps
+  /**
+   * The data to update the products with.
+   */
   update: Omit<ProductTypes.UpdateProductDTO, "variants"> & {
+    /**
+     * The sales channels that the products are available in.
+     */
     sales_channels?: { id: string }[]
+    /**
+     * The variants to update.
+     */
     variants?: UpdateProductVariantWorkflowInputDTO[]
   }
 } & AdditionalData
 
+/**
+ * Update one or more products, along with custom data that's passed to the workflow's hooks.
+ */
 export type UpdateProductsWorkflowInputProducts = {
+  /**
+   * The products to update.
+   */
   products: (Omit<ProductTypes.UpsertProductDTO, "variants"> & {
+    /**
+     * The sales channels that the products are available in.
+     */
     sales_channels?: { id: string }[]
+    /**
+     * The variants to update.
+     */
     variants?: UpdateProductVariantWorkflowInputDTO[]
   })[]
 } & AdditionalData
 
+/**
+ * The data to update one or more products, along with custom data that's passed to the workflow's hooks.
+ */
 export type UpdateProductWorkflowInput =
   | UpdateProductsWorkflowInputSelector
   | UpdateProductsWorkflowInputProducts
@@ -215,7 +245,68 @@ function prepareToDeleteSalesChannelLinks({
 
 export const updateProductsWorkflowId = "update-products"
 /**
- * This workflow updates one or more products.
+ * This workflow updates one or more products. It's used by the [Update Product Admin API Route](https://docs.medusajs.com/api/admin#products_postproductsid).
+ * 
+ * This workflow has a hook that allows you to perform custom actions on the updated products. For example, you can pass under `additional_data` custom data that 
+ * allows you to update custom data models linked to the products.
+ * 
+ * You can also use this workflow within your own custom workflows, allowing you to wrap custom logic around product update.
+ * 
+ * @example
+ * To update products by their IDs:
+ * 
+ * ```ts
+ * const { result } = await updateProductsWorkflow(container)
+ * .run({
+ *   input: {
+ *     products: [
+ *       {
+ *         id: "prod_123",
+ *         title: "Shirts"
+ *       },
+ *       {
+ *         id: "prod_321",
+ *         variants: [
+ *           {
+ *             id: "variant_123",
+ *             options: {
+ *               Size: "S"
+ *             }
+ *           }
+ *         ]
+ *       }
+ *     ],
+ *     additional_data: {
+ *       erp_id: "erp_123"
+ *     }
+ *   }
+ * })
+ * ```
+ * 
+ * You can also update products by a selector:
+ * 
+ * ```ts
+ * const { result } = await updateProductsWorkflow(container)
+ * .run({
+ *   input: {
+ *     selector: {
+ *       type_id: ["ptyp_123"]
+ *     },
+ *     update: {
+ *       description: "This is a shirt product"
+ *     },
+ *     additional_data: {
+ *       erp_id: "erp_123"
+ *     }
+ *   }
+ * })
+ * ```
+ * 
+ * @summary
+ * 
+ * Update one or more products with options and variants.
+ * 
+ * @property hooks.productsUpdated - This hook is executed after the products are updated. You can consume this hook to perform custom actions on the updated products.
  */
 export const updateProductsWorkflow = createWorkflow(
   updateProductsWorkflowId,

packages/core/core-flows/src/promotion/workflows/create-campaigns.ts

@@ -1,23 +1,61 @@
 import { AdditionalData, CreateCampaignDTO } from "@medusajs/framework/types"
 import {
-  WorkflowData,
   WorkflowResponse,
   createHook,
   createWorkflow,
 } from "@medusajs/framework/workflows-sdk"
 import { createCampaignsStep } from "../steps"
 
+/**
+ * The data to create one or more campaigns, along with custom data that's passed to the workflow's hooks.
+ */
 export type CreateCampaignsWorkflowInput = {
+  /**
+   * The campaigns to create.
+   */
   campaignsData: CreateCampaignDTO[]
 } & AdditionalData
 
 export const createCampaignsWorkflowId = "create-campaigns"
 /**
- * This workflow creates one or more campaigns.
+ * This workflow creates one or more campaigns. It's used by the [Create Campaign Admin API Route](https://docs.medusajs.com/api/admin#campaigns_postcampaigns).
+ * 
+ * This workflow has a hook that allows you to perform custom actions on the created campaigns. For example, you can pass under `additional_data` custom data that
+ * allows you to create custom data models linked to the campaigns.
+ * 
+ * You can also use this workflow within your own custom workflows, allowing you to wrap custom logic around creating campaigns.
+ * 
+ * @example
+ * const { result } = await createCampaignsWorkflow(container)
+ * .run({
+ *   input: {
+ *     campaignsData: [
+ *       {
+ *         name: "Launch Promotions",
+ *         campaign_identifier: "GA-123456",
+ *         starts_at: new Date("2025-01-01"),
+ *         ends_at: new Date("2026-01-01"),
+ *         budget: {
+ *           type: "usage",
+ *           limit: 100,
+ *         }
+ *       }
+ *     ],
+ *     additional_data: {
+ *       target_audience: "new_customers"
+ *     }
+ *   }
+ * })
+ * 
+ * @summary
+ * 
+ * Create one or more campaigns.
+ * 
+ * @property hooks.campaignsCreated - This hook is executed after the campaigns are created. You can consume this hook to perform custom actions on the created campaigns.
  */
 export const createCampaignsWorkflow = createWorkflow(
   createCampaignsWorkflowId,
-  (input: WorkflowData<CreateCampaignsWorkflowInput>) => {
+  (input: CreateCampaignsWorkflowInput) => {
     const createdCampaigns = createCampaignsStep(input.campaignsData)
     const campaignsCreated = createHook("campaignsCreated", {
       campaigns: createdCampaigns,

packages/core/core-flows/src/promotion/workflows/create-promotions.ts

@@ -1,23 +1,62 @@
 import { AdditionalData, CreatePromotionDTO } from "@medusajs/framework/types"
 import {
-  WorkflowData,
   WorkflowResponse,
   createHook,
   createWorkflow,
 } from "@medusajs/framework/workflows-sdk"
 import { createPromotionsStep } from "../steps"
 
+/**
+ * The data to create one or more promotions, along with custom data that's passed to the workflow's hooks.
+ */
 export type CreatePromotionsWorkflowInput = {
+  /**
+   * The promotions to create.
+   */
   promotionsData: CreatePromotionDTO[]
 } & AdditionalData
 
 export const createPromotionsWorkflowId = "create-promotions"
 /**
- * This workflow creates one or more promotions.
+ * This workflow creates one or more promotions. It's used by the [Create Promotion Admin API Route](https://docs.medusajs.com/api/admin#promotions_postpromotions).
+ * 
+ * This workflow has a hook that allows you to perform custom actions on the created promotion. For example, you can pass under `additional_data` custom data that
+ * allows you to create custom data models linked to the promotions.
+ * 
+ * You can also use this workflow within your own custom workflows, allowing you to wrap custom logic around creating promotions.
+ * 
+ * @example
+ * const { result } = await createPromotionsWorkflow(container)
+ * .run({
+ *   input: {
+ *     promotionsData: [
+ *       {
+ *         code: "10OFF",
+ *         type: "standard",
+ *         application_method: {
+ *           type: "percentage",
+ *           target_type: "items",
+ *           allocation: "across",
+ *           value: 10,
+ *           currency_code: "usd"
+ *         }
+ *       }
+ *     ],
+ *     additional_data: {
+ *       external_id: "123"
+ *     }
+ *   }
+ * })
+ * 
+ * @summary
+ * 
+ * Create one or more promotions.
+ * 
+ * @property hooks.promotionsCreated - This hook is executed after the promotions are created. You can consume this hook to perform custom actions on the created promotions.
  */
 export const createPromotionsWorkflow = createWorkflow(
   createPromotionsWorkflowId,
-  (input: WorkflowData<CreatePromotionsWorkflowInput>) => {
+  (input: CreatePromotionsWorkflowInput) => {
     const createdPromotions = createPromotionsStep(input.promotionsData)
     const promotionsCreated = createHook("promotionsCreated", {
       promotions: createdPromotions,

packages/core/core-flows/src/promotion/workflows/update-campaigns.ts

@@ -1,23 +1,56 @@
 import { AdditionalData, UpdateCampaignDTO } from "@medusajs/framework/types"
 import {
-  WorkflowData,
   WorkflowResponse,
   createHook,
   createWorkflow,
 } from "@medusajs/framework/workflows-sdk"
 import { updateCampaignsStep } from "../steps"
 
+/**
+ * The data to update one or more campaigns, along with custom data that's passed to the workflow's hooks.
+ */
 export type UpdateCampaignsWorkflowInput = {
+  /**
+   * The campaigns to update.
+   */
   campaignsData: UpdateCampaignDTO[]
 } & AdditionalData
 
 export const updateCampaignsWorkflowId = "update-campaigns"
 /**
- * This workflow updates one or more campaigns.
+ * This workflow updates one or more campaigns. It's used by the [Update Campaign Admin API Route](https://docs.medusajs.com/api/admin#campaigns_postcampaignsid).
+ * 
+ * This workflow has a hook that allows you to perform custom actions on the updated campaigns. For example, you can pass under `additional_data` custom data that
+ * allows you to update custom data models linked to the campaigns.
+ * 
+ * You can also use this workflow within your own custom workflows, allowing you to wrap custom logic around updating campaigns.
+ * 
+ * @example
+ * const { result } = await updateCampaignsWorkflow(container)
+ * .run({
+ *   input: {
+ *     campaignsData: [
+ *       {
+ *         id: "camp_123",
+ *         name: "Launch Promotions",
+ *         ends_at: new Date("2026-01-01"),
+ *       }
+ *     ],
+ *     additional_data: {
+ *       target_audience: "new_customers"
+ *     }
+ *   }
+ * })
+ * 
+ * @summary
+ * 
+ * Update one or more campaigns.
+ * 
+ * @property hooks.campaignsUpdated - This hook is executed after the campaigns are updated. You can consume this hook to perform custom actions on the updated campaigns.
  */
 export const updateCampaignsWorkflow = createWorkflow(
   updateCampaignsWorkflowId,
-  (input: WorkflowData<UpdateCampaignsWorkflowInput>) => {
+  (input: UpdateCampaignsWorkflowInput) => {
     const updatedCampaigns = updateCampaignsStep(input.campaignsData)
     const campaignsUpdated = createHook("campaignsUpdated", {
       campaigns: updatedCampaigns,

packages/core/core-flows/src/promotion/workflows/update-promotions.ts

@@ -1,23 +1,55 @@
 import { AdditionalData, UpdatePromotionDTO } from "@medusajs/framework/types"
 import {
-  WorkflowData,
   WorkflowResponse,
   createHook,
   createWorkflow,
 } from "@medusajs/framework/workflows-sdk"
 import { updatePromotionsStep } from "../steps"
 
+/**
+ * The data to update one or more promotions, along with custom data that's passed to the workflow's hooks.
+ */
 export type UpdatePromotionsWorkflowInput = {
+  /**
+   * The promotions to update.
+   */
   promotionsData: UpdatePromotionDTO[]
 } & AdditionalData
 
 export const updatePromotionsWorkflowId = "update-promotions"
 /**
- * This workflow updates one or more promotions.
+ * This workflow updates one or more promotions. It's used by the [Update Promotion Admin API Route](https://docs.medusajs.com/api/admin#promotions_postpromotionsid).
+ * 
+ * This workflow has a hook that allows you to perform custom actions on the updated promotion. For example, you can pass under `additional_data` custom data that
+ * allows you to update custom data models linked to the promotions.
+ * 
+ * You can also use this workflow within your own custom workflows, allowing you to wrap custom logic around updating promotions.
+ * 
+ * @example
+ * const { result } = await updatePromotionsWorkflow(container)
+ * .run({
+ *   input: {
+ *     promotionsData: [
+ *       {
+ *         id: "promo_123",
+ *         code: "10OFF",
+ *       }
+ *     ],
+ *     additional_data: {
+ *       external_id: "123"
+ *     }
+ *   }
+ * })
+ * 
+ * @summary
+ * 
+ * Update one or more promotions.
+ * 
+ * @property hooks.promotionsUpdated - This hook is executed after the promotions are updated. You can consume this hook to perform custom actions on the updated promotions.
  */
 export const updatePromotionsWorkflow = createWorkflow(
   updatePromotionsWorkflowId,
-  (input: WorkflowData<UpdatePromotionsWorkflowInput>) => {
+  (input: UpdatePromotionsWorkflowInput) => {
     const updatedPromotions = updatePromotionsStep(input.promotionsData)
     const promotionsUpdated = createHook("promotionsUpdated", {
       promotions: updatedPromotions,

packages/core/types/src/cart/workflows.ts

@@ -272,16 +272,60 @@ export interface AddToCartWorkflowInputDTO {
   items: CreateCartCreateLineItemDTO[]
 }
 
+/**
+ * The details to update in a cart.
+ */
 export interface UpdateCartWorkflowInputDTO {
+  /**
+   * The ID of the cart to update.
+   */
   id: string
+
+  /**
+   * An array of promotional codes applied on the cart.
+   */
   promo_codes?: string[]
+
+  /**
+   * The ID of the cart's region.
+   */
   region_id?: string
+
+  /**
+   * The ID of the cart's customer.
+   */
   customer_id?: string | null
+
+  /**
+   * The ID of the cart's sales channel.
+   */
   sales_channel_id?: string | null
+
+  /**
+   * The email address of the cart's customer.
+   */
   email?: string | null
+
+  /**
+   * The currency code for the cart.
+   * 
+   * @example usd
+   */
   currency_code?: string
+
+  /**
+   * Custom key-value pairs of data related to the cart.
+   */
   metadata?: Record<string, unknown> | null
+
+  /**
+   * The cart's shipping address. You can either update the cart's existing shipping address, or create a new one.
+   */
   shipping_address?: CreateAddressDTO | UpdateAddressDTO | null
+
+  /**
+   * The cart's billing address. You can either update the cart's existing billing address, or create a new one.
+   */
   billing_address?: CreateAddressDTO | UpdateAddressDTO | null
 }
 

packages/core/types/src/http/common/additional_data.ts

@@ -5,5 +5,10 @@
  * Learn more in [this documentation](https://docs.medusajs.com/learn/fundamentals/api-routes/additional-data).
  */
 export type AdditionalData = {
+  /**
+   * Additional data that can be passed through the `additional_data` property in HTTP requests.
+   * 
+   * Learn more in [this documentation](https://docs.medusajs.com/learn/fundamentals/api-routes/additional-data).
+   */
   additional_data?: Record<string, unknown>
 }

packages/core/types/src/workflow/order/cancel-fulfillment.ts

@@ -1,6 +1,18 @@
 export interface CancelOrderFulfillmentWorkflowInput {
+  /**
+   * The ID of the order to cancel its fulfillment.
+   */
   order_id: string
+  /**
+   * The ID of the fulfillment to cancel.
+   */
   fulfillment_id: string
+  /**
+   * Whether to notify the customer about the cancellation.
+   */
   no_notification?: boolean
+  /**
+   * The ID of the user that canceled the fulfillment.
+   */
   canceled_by?: string
 }

packages/core/types/src/workflow/order/create-fulfillment.ts

@@ -2,19 +2,68 @@ import { OrderLineItemDTO } from "../../order"
 import { BigNumberInput } from "../../totals"
 import { CreateFulfillmentLabelWorkflowDTO } from "../fulfillment/create-fulfillment"
 
+/**
+ * The details of an item in the fulfillment.
+ */
 interface CreateOrderFulfillmentItem {
+  /**
+   * The ID of the order's item to fulfill.
+   */
   id: string
+  /**
+   * The quantity of the item to fulfill.
+   */
   quantity: BigNumberInput
 }
 
+/**
+ * The details of the fulfillment to create.
+ */
 export interface CreateOrderFulfillmentWorkflowInput {
+  /**
+   * The ID of the order to create the fulfillment for.
+   */
   order_id: string
+
+  /**
+   * The list of items in the order. If not provided, the order's items are used.
+   */
   items_list?: OrderLineItemDTO[]
-  created_by?: string // The id of the authenticated user
+
+  /**
+   * The ID of the user who created the fulfillment.
+   */
+  created_by?: string
+
+  /**
+   * A list of items to be fulfilled.
+   */
   items: CreateOrderFulfillmentItem[]
+
+  /**
+   * The labels to associate with the order.
+   */
   labels?: CreateFulfillmentLabelWorkflowDTO[]
+
+  /**
+   * Whether the notify the customer about the fulfillment.
+   */
   no_notification?: boolean
+
+  /**
+   * The ID of the stock location to fulfill items from. If not provided, the workflow uses the ID
+   * of the location associated with the shipping option used by the order's
+   * shipping method.
+   */
   location_id?: string | null
+
+  /**
+   * Custom k-value pairs related to the fulfillment.
+   */
   metadata?: Record<string, any> | null
+
+  /**
+   * Whether the fulfillment should be shipped.
+   */
   requires_shipping?: boolean
 }

packages/core/types/src/workflow/order/create-shipment.ts

@@ -2,17 +2,50 @@ import { MetadataType } from "../../common"
 import { BigNumberInput } from "../../totals"
 import { CreateFulfillmentLabelWorkflowDTO } from "../fulfillment"
 
+/**
+ * The details of an item in the shipment.
+ */
 interface CreateOrderShipmentItem {
+  /**
+   * The ID of the order's item to ship.
+   */
   id: string
+  /**
+   * The quantity of the item to ship.
+   */
   quantity: BigNumberInput
 }
 
+/**
+ * The details required to create a shipment for an order.
+ */
 export interface CreateOrderShipmentWorkflowInput {
+  /**
+   * The ID of the order to create a shipment for.
+   */
   order_id: string
+  /**
+   * The ID of the fulfillment to create a shipment for.
+   */
   fulfillment_id: string
-  created_by?: string // The id of the authenticated user
+  /**
+   * The ID of the user creating the shipment.
+   */
+  created_by?: string
+  /**
+   * The items to create a shipment for.
+   */
   items: CreateOrderShipmentItem[]
+  /**
+   * The shipment's labels.
+   */
   labels?: CreateFulfillmentLabelWorkflowDTO[]
+  /**
+   * Whether to notify the customer about the shipment.
+   */
   no_notification?: boolean
+  /**
+   * Custom key-value pairs related to the shipment.
+   */
   metadata?: MetadataType
 }

packages/core/types/src/workflows/products/mutations.ts

@@ -1,20 +1,41 @@
 import { PricingTypes, ProductTypes } from "../../bundles"
 
+/**
+ * The details of the variant to create.
+ */
 export type CreateProductVariantWorkflowInputDTO =
   ProductTypes.CreateProductVariantDTO & {
+    /**
+     * The variant's prices.
+     */
     prices?: PricingTypes.CreateMoneyAmountDTO[]
   }
 
+/**
+ * The details of the variant to update.
+ */
 export type UpdateProductVariantWorkflowInputDTO =
   ProductTypes.UpsertProductVariantDTO & {
+    /**
+     * The variant's prices.
+     */
     prices?: PricingTypes.CreateMoneyAmountDTO[]
   }
 
+/**
+ * The details of the product to create.
+ */
 export type CreateProductWorkflowInputDTO = Omit<
   ProductTypes.CreateProductDTO,
   "variants"
 > & {
+  /**
+   * The sales channels that the product is available in.
+   */
   sales_channels?: { id: string }[]
+  /**
+   * The product's variants.
+   */
   variants?: CreateProductVariantWorkflowInputDTO[]
 }