chore(core-flows,types): improve tsdocs of workflows [1] (medusajs#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: "[email protected]",
+ *       },
+ *     ],
+ *     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<
-      OrderWorkflow.CancelOrderFulfillmentWorkflowInput & AdditionalData
-    >
+    input: WorkflowData<CancelOrderFulfillmentWorkflowInput>
   ) => {
     const order: OrderDTO & { fulfillments: FulfillmentDTO[] } =
       useRemoteQueryStep({