chore(core-flows): improve TSDocs of customer and customer groups workflows / steps (#10993)

* improve customer tsdocs

* finished improving tsdocs

* fix build error

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

@@ -75,6 +75,8 @@ export const addShippingMethodToCartWorkflowId = "add-shipping-method-to-cart"
  * @summary
  * 
  * Add a shipping method to a cart.
+ * 
+ * @property hooks.validate - This hook is executed before all operations. You can consume this hook to perform any custom validation. If validation fails, you can throw an error to stop the workflow execution.
  */
 export const addShippingMethodToCartWorkflow = createWorkflow(
   addShippingMethodToCartWorkflowId,

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

@@ -63,6 +63,8 @@ export const addToCartWorkflowId = "add-to-cart"
  * @summary
  * 
  * Add a line item to a cart.
+ * 
+ * @property hooks.validate - This hook is executed before all operations. You can consume this hook to perform any custom validation. If validation fails, you can throw an error to stop the workflow execution.
  */
 export const addToCartWorkflow = createWorkflow(
   addToCartWorkflowId,

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

@@ -75,6 +75,8 @@ export const completeCartWorkflowId = "complete-cart"
  * @summary
  * 
  * Complete a cart and place an order.
+ * 
+ * @property hooks.validate - This hook is executed before all operations. You can consume this hook to perform any custom validation. If validation fails, you can throw an error to stop the workflow execution.
  */
 export const completeCartWorkflow = createWorkflow(
   {

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

@@ -73,7 +73,7 @@ export const createCartWorkflowId = "create-cart"
  *
  * Create a cart specifying region, items, and more.
  *
- * @property hooks.validate - This hook is executed before all operations. You can consume this hook to perform any custom validation.
+ * @property hooks.validate - This hook is executed before all operations. You can consume this hook to perform any custom validation. If validation fails, you can throw an error to stop the workflow execution.
  * @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(

packages/core/core-flows/src/cart/workflows/refresh-cart-items.ts

@@ -65,6 +65,8 @@ export const refreshCartItemsWorkflowId = "refresh-cart-items"
  * @summary
  * 
  * Refresh a cart's details after an update.
+ * 
+ * @property hooks.validate - This hook is executed before all operations. You can consume this hook to perform any custom validation. If validation fails, you can throw an error to stop the workflow execution.
  */
 export const refreshCartItemsWorkflow = createWorkflow(
   refreshCartItemsWorkflowId,

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

@@ -42,6 +42,8 @@ export const refreshCartShippingMethodsWorkflowId =
  * @summary
  * 
  * Refresh a cart's shipping methods after an update.
+ * 
+ * @property hooks.validate - This hook is executed before all operations. You can consume this hook to perform any custom validation. If validation fails, you can throw an error to stop the workflow execution.
  */
 export const refreshCartShippingMethodsWorkflow = createWorkflow(
   refreshCartShippingMethodsWorkflowId,

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

@@ -46,6 +46,8 @@ export const refreshPaymentCollectionForCartWorkflowId =
  * @summary
  * 
  * Refresh a cart's payment collection details.
+ * 
+ * @property hooks.validate - This hook is executed before all operations. You can consume this hook to perform any custom validation. If validation fails, you can throw an error to stop the workflow execution.
  */
 export const refreshPaymentCollectionForCartWorkflow = createWorkflow(
   refreshPaymentCollectionForCartWorkflowId,

packages/core/core-flows/src/cart/workflows/transfer-cart-customer.ts

@@ -44,6 +44,8 @@ export const transferCartCustomerWorkflowId = "transfer-cart-customer"
  * @summary
  * 
  * Refresh a cart's payment collection details.
+ * 
+ * @property hooks.validate - This hook is executed before all operations. You can consume this hook to perform any custom validation. If validation fails, you can throw an error to stop the workflow execution.
  */
 export const transferCartCustomerWorkflow = createWorkflow(
   transferCartCustomerWorkflowId,

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

@@ -64,6 +64,8 @@ export const updateCartPromotionsWorkflowId = "update-cart-promotions"
  * @summary
  * 
  * Update a cart's applied promotions to add, replace, or remove them.
+ * 
+ * @property hooks.validate - This hook is executed before all operations. You can consume this hook to perform any custom validation. If validation fails, you can throw an error to stop the workflow execution.
  */
 export const updateCartPromotionsWorkflow = createWorkflow(
   updateCartPromotionsWorkflowId,

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

@@ -76,7 +76,7 @@ export const updateCartWorkflowId = "update-cart"
  *
  * Update a cart's details, such as region, address, and more.
  *
- * @property hooks.validate - This hook is executed before all operations. You can consume this hook to perform any custom validation.
+ * @property hooks.validate - This hook is executed before all operations. You can consume this hook to perform any custom validation. If validation fails, you can throw an error to stop the workflow execution.
  * @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(

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

@@ -44,6 +44,8 @@ export const updateLineItemInCartWorkflowId = "update-line-item-in-cart"
  * @summary
  * 
  * Update a cart's line item.
+ *
+ * @property hooks.validate - This hook is executed before all operations. You can consume this hook to perform any custom validation. If validation fails, you can throw an error to stop the workflow execution.
  */
 export const updateLineItemInCartWorkflow = createWorkflow(
   updateLineItemInCartWorkflowId,

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

@@ -5,13 +5,18 @@ import {
 import { Modules } from "@medusajs/framework/utils"
 import { StepResponse, createStep } from "@medusajs/framework/workflows-sdk"
 
+/**
+ * The data to create customer groups.
+ */
+export type CreateCustomerGroupsStepInput = CreateCustomerGroupDTO[]
+
 export const createCustomerGroupsStepId = "create-customer-groups"
 /**
  * This step creates one or more customer groups.
  */
 export const createCustomerGroupsStep = createStep(
   createCustomerGroupsStepId,
-  async (data: CreateCustomerGroupDTO[], { container }) => {
+  async (data: CreateCustomerGroupsStepInput, { container }) => {
     const service = container.resolve<ICustomerModuleService>(Modules.CUSTOMER)
 
     const createdCustomerGroups = await service.createCustomerGroups(data)

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

@@ -2,13 +2,18 @@ import { ICustomerModuleService } from "@medusajs/framework/types"
 import { Modules } from "@medusajs/framework/utils"
 import { createStep, StepResponse } from "@medusajs/framework/workflows-sdk"
 
+/**
+ * The IDs of the customer groups to delete.
+ */
+export type DeleteCustomerGroupsStepInput = string[]
+
 export const deleteCustomerGroupStepId = "delete-customer-groups"
 /**
  * This step deletes one or more customer groups.
  */
 export const deleteCustomerGroupStep = createStep(
   deleteCustomerGroupStepId,
-  async (ids: string[], { container }) => {
+  async (ids: DeleteCustomerGroupsStepInput, { container }) => {
     const service = container.resolve<ICustomerModuleService>(Modules.CUSTOMER)
 
     await service.softDeleteCustomerGroups(ids)

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

@@ -8,7 +8,14 @@ import { StepResponse, createStep } from "@medusajs/framework/workflows-sdk"
 export const linkCustomerGroupsToCustomerStepId =
   "link-customers-to-customer-group"
 /**
- * This step creates one or more links between a customer and customer groups records.
+ * This step manages the customer groups of a customer.
+ * 
+ * @example
+ * const data = linkCustomerGroupsToCustomerStep({
+ *   id: "cus_123",
+ *   add: ["cusgrp_123"],
+ *   remove: ["cusgrp_456"]
+ * })
  */
 export const linkCustomerGroupsToCustomerStep = createStep(
   linkCustomerGroupsToCustomerStepId,

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

@@ -8,7 +8,14 @@ import { StepResponse, createStep } from "@medusajs/framework/workflows-sdk"
 export const linkCustomersToCustomerGroupStepId =
   "link-customers-to-customer-group"
 /**
- * This step creates one or more links between customer and customer group records.
+ * This step manages the customers in a customer group.
+ * 
+ * @example
+ * const data = linkCustomersToCustomerGroupStep({
+ *   id: "cusgrp_123",
+ *   add: ["cus_123"],
+ *   remove: ["cus_456"]
+ * })
  */
 export const linkCustomersToCustomerGroupStep = createStep(
   linkCustomersToCustomerGroupStepId,

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

@@ -10,14 +10,33 @@ import {
 } from "@medusajs/framework/utils"
 import { StepResponse, createStep } from "@medusajs/framework/workflows-sdk"
 
+/**
+ * The data to update customer groups.
+ */
 export type UpdateCustomerGroupStepInput = {
+  /**
+   * The filters to select the customer groups to update.
+   */
   selector: FilterableCustomerGroupProps
+  /**
+   * The data to update in the customer groups.
+   */
   update: CustomerGroupUpdatableFields
 }
 
 export const updateCustomerGroupStepId = "update-customer-groups"
 /**
  * This step updates one or more customer groups.
+ * 
+ * @example
+ * const data = updateCustomerGroupsStep({
+ *   selector: {
+ *     id: "cusgrp_123"
+ *   },
+ *   update: {
+ *     name: "VIP"
+ *   }
+ * })
  */
 export const updateCustomerGroupsStep = createStep(
   updateCustomerGroupStepId,

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

@@ -9,19 +9,51 @@ import {
 } from "@medusajs/framework/workflows-sdk"
 import { createCustomerGroupsStep } from "../steps"
 
+/**
+ * The data to create customer groups.
+ */
 export type CreateCustomerGroupsWorkflowInput = {
+  /**
+   * The customer groups to create.
+   */
   customersData: CreateCustomerGroupDTO[]
 }
 
+/**
+ * The created customer groups.
+ */
+export type CreateCustomerGroupsWorkflowOutput = CustomerGroupDTO[]
+
 export const createCustomerGroupsWorkflowId = "create-customer-groups"
 /**
- * This workflow creates one or more customer groups.
+ * This workflow creates one or more customer groups. It's used by the
+ * [Create Customer Group Admin API Route](https://docs.medusajs.com/api/admin#customer-groups_postcustomergroups).
+ * 
+ * You can use this workflow within your customizations or your own custom workflows, allowing you to 
+ * create customer groups within your custom flows. For example, you can create customer groups to segregate
+ * customers by age group or purchase habits.
+ * 
+ * @example
+ * const { result } = await createCustomerGroupsWorkflow(container)
+ * .run({
+ *   input: {
+ *     customersData: [
+ *       {
+ *         name: "VIP"
+ *       }
+ *     ]
+ *   }
+ * })
+ * 
+ * @summary
+ * 
+ * Create one or more customer groups.
  */
 export const createCustomerGroupsWorkflow = createWorkflow(
   createCustomerGroupsWorkflowId,
   (
     input: WorkflowData<CreateCustomerGroupsWorkflowInput>
-  ): WorkflowResponse<CustomerGroupDTO[]> => {
+  ): WorkflowResponse<CreateCustomerGroupsWorkflowOutput> => {
     return new WorkflowResponse(createCustomerGroupsStep(input.customersData))
   }
 )

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

@@ -1,11 +1,35 @@
 import { WorkflowData, createWorkflow } from "@medusajs/framework/workflows-sdk"
 import { deleteCustomerGroupStep } from "../steps"
 
-export type DeleteCustomerGroupsWorkflowInput = { ids: string[] }
+/**
+ * The data to delete customer groups.
+ */
+export type DeleteCustomerGroupsWorkflowInput = { 
+  /**
+   * The IDs of the customer groups to delete.
+   */
+  ids: string[]
+}
 
 export const deleteCustomerGroupsWorkflowId = "delete-customer-groups"
 /**
- * This workflow deletes one or more customer groups.
+ * This workflow deletes one or more customer groups. It's used by the
+ * [Delete Customer Group Admin API Route](https://docs.medusajs.com/api/admin#customer-groups_deletecustomergroupsid).
+ * 
+ * You can use this workflow within your customizations or your own custom workflows, allowing you to
+ * delete customer groups within your custom flows.
+ * 
+ * @example
+ * const { result } = await deleteCustomerGroupsWorkflow(container)
+ * .run({
+ *   input: {
+ *     ids: ["cusgrp_123"]
+ *   }
+ * })
+ * 
+ * @summary
+ * 
+ * Delete one or more customer groups.
  */
 export const deleteCustomerGroupsWorkflow = createWorkflow(
   deleteCustomerGroupsWorkflowId,

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

@@ -2,14 +2,41 @@ import { LinkWorkflowInput } from "@medusajs/framework/types"
 import { WorkflowData, createWorkflow } from "@medusajs/framework/workflows-sdk"
 import { linkCustomerGroupsToCustomerStep } from "../steps"
 
+/**
+ * The data to manage the customer groups of a customer.
+ * 
+ * @property id - The ID of the customer to manage its groups.
+ * @property add - The IDs of the customer groups to add the customer to.
+ * @property remove - The IDs of the customer groups to remove the customer from.
+ */
+export type LinkCustomerGroupsToCustomerWorkflowInput = LinkWorkflowInput
+
 export const linkCustomerGroupsToCustomerWorkflowId =
   "link-customer-groups-to-customer"
 /**
- * This workflow creates one or more links between a customer and customer groups.
+ * This workflow manages the customer groups a customer is in. It's used by the 
+ * [Manage Groups of Customer Admin API Route](https://docs.medusajs.com/api/admin#customers_postcustomersidcustomergroups).
+ * 
+ * You can use this workflow within your customizations or your own custom workflows, allowing you to
+ * manage the customer groups of a customer in your custom flow.
+ * 
+ * @example
+ * const { result } = await linkCustomerGroupsToCustomerWorkflow(container)
+ * .run({
+ *   input: {
+ *     id: "cus_123",
+ *     add: ["cusgrp_123"],
+ *     remove: ["cusgrp_456"]
+ *   }
+ * })
+ * 
+ * @summary
+ * 
+ * Manage groups of a customer.
  */
 export const linkCustomerGroupsToCustomerWorkflow = createWorkflow(
   linkCustomerGroupsToCustomerWorkflowId,
-  (input: WorkflowData<LinkWorkflowInput>): WorkflowData<void> => {
+  (input: WorkflowData<LinkCustomerGroupsToCustomerWorkflowInput>): WorkflowData<void> => {
     return linkCustomerGroupsToCustomerStep(input)
   }
 )

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

@@ -2,14 +2,41 @@ import { LinkWorkflowInput } from "@medusajs/framework/types"
 import { WorkflowData, createWorkflow } from "@medusajs/framework/workflows-sdk"
 import { linkCustomersToCustomerGroupStep } from "../steps"
 
+/**
+ * The data to manage the customers of a group.
+ * 
+ * @property id - The ID of the customer group to manage its customers.
+ * @property add - The IDs of the customers to add to the customer group.
+ * @property remove - The IDs of the customers to remove from the customer group.
+ */
+export type LinkCustomersToCustomerGroupWorkflow = LinkWorkflowInput
+
 export const linkCustomersToCustomerGroupWorkflowId =
   "link-customers-to-customer-group"
 /**
- * This workflow creates one or more links between customer and customer group records.
+ * This workflow manages the customers of a customer group. It's used by the 
+ * [Manage Customers of Group Admin API Route](https://docs.medusajs.com/api/admin#customer-groups_postcustomergroupsidcustomers).
+ * 
+ * You can use this workflow within your customizations or your own custom workflows, allowing you to
+ * manage the customers of a customer group within your custom flows.
+ * 
+ * @example
+ * const { result } = await linkCustomersToCustomerGroupWorkflow(container)
+ * .run({
+ *   input: {
+ *     id: "cusgrp_123",
+ *     add: ["cus_123"],
+ *     remove: ["cus_456"]
+ *   }
+ * })
+ * 
+ * @summary
+ * 
+ * Manage the customers of a customer group.
  */
 export const linkCustomersToCustomerGroupWorkflow = createWorkflow(
   linkCustomersToCustomerGroupWorkflowId,
-  (input: WorkflowData<LinkWorkflowInput>): WorkflowData<void> => {
+  (input: WorkflowData<LinkCustomersToCustomerGroupWorkflow>): WorkflowData<void> => {
     return linkCustomersToCustomerGroupStep(input)
   }
 )

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

@@ -10,20 +10,55 @@ import {
 } from "@medusajs/framework/workflows-sdk"
 import { updateCustomerGroupsStep } from "../steps"
 
+/**
+ * The data to update customer groups.
+ */
 export type UpdateCustomerGroupsWorkflowInput = {
+  /**
+   * The filter to select the customer groups to update.
+   */
   selector: FilterableCustomerGroupProps
+  /**
+   * The data to update in the customer group.
+   */
   update: CustomerGroupUpdatableFields
 }
 
+/**
+ * The updated customer groups.
+ */
+export type UpdateCustomerGroupsWorkflowOutput = CustomerGroupDTO[]
+
 export const updateCustomerGroupsWorkflowId = "update-customer-groups"
 /**
- * This workflow updates one or more customer groups.
+ * This workflow updates one or more customer groups. It's used by the
+ * [Update Customer Group Admin API Route](https://docs.medusajs.com/api/admin#customer-groups_postcustomergroupsid).
+ * 
+ * You can use this workflow within your customizations or your own custom workflows, allowing you to
+ * update customer groups within your custom flows.
+ * 
+ * @example
+ * const { result } = await updateCustomerGroupsWorkflow(container)
+ * .run({
+ *   input: {
+ *     selector: {
+ *       id: "cusgrp_123"
+ *     },
+ *     update: {
+ *       name: "VIP"
+ *     }
+ *   }
+ * })
+ * 
+ * @summary
+ * 
+ * Update one or more customer groups.
  */
 export const updateCustomerGroupsWorkflow = createWorkflow(
   updateCustomerGroupsWorkflowId,
   (
     input: WorkflowData<UpdateCustomerGroupsWorkflowInput>
-  ): WorkflowResponse<CustomerGroupDTO[]> => {
+  ): WorkflowResponse<UpdateCustomerGroupsWorkflowOutput> => {
     return new WorkflowResponse(updateCustomerGroupsStep(input))
   }
 )

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

@@ -5,13 +5,32 @@ import {
 import { Modules } from "@medusajs/framework/utils"
 import { StepResponse, createStep } from "@medusajs/framework/workflows-sdk"
 
+/**
+ * The data to create one or more customer addresses.
+ */
+export type CreateCustomerAddressesStepInput = CreateCustomerAddressDTO[]
+
 export const createCustomerAddressesStepId = "create-customer-addresses"
 /**
  * This step creates one or more customer addresses.
+ * 
+ * @example
+ * const data = createCustomerAddressesStep([
+ *   {
+ *     customer_id: "cus_123",
+ *     first_name: "John",
+ *     last_name: "Doe",
+ *     address_1: "123 Main St",
+ *     city: "Anytown",
+ *     province: "NY",
+ *     postal_code: "12345",
+ *     country_code: "us",
+ *   }
+ * ])
  */
 export const createCustomerAddressesStep = createStep(
   createCustomerAddressesStepId,
-  async (data: CreateCustomerAddressDTO[], { container }) => {
+  async (data: CreateCustomerAddressesStepInput, { container }) => {
     const service = container.resolve<ICustomerModuleService>(Modules.CUSTOMER)
 
     const addresses = await service.createCustomerAddresses(data)

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

@@ -5,13 +5,27 @@ import {
 import { Modules } from "@medusajs/framework/utils"
 import { StepResponse, createStep } from "@medusajs/framework/workflows-sdk"
 
+/**
+ * The data to create one or more customers.
+ */
+export type CreateCustomersStepInput = CreateCustomerDTO[]
+
 export const createCustomersStepId = "create-customers"
 /**
  * This step creates one or more customers.
+ * 
+ * @example
+ * const data = createCustomersStep([
+ *   {
+ *     first_name: "John",
+ *     last_name: "Doe",
+ *     email: "customer@example.com",
+ *   }
+ * ])
  */
 export const createCustomersStep = createStep(
   createCustomersStepId,
-  async (data: CreateCustomerDTO[], { container }) => {
+  async (data: CreateCustomersStepInput, { container }) => {
     const service = container.resolve<ICustomerModuleService>(Modules.CUSTOMER)
 
     const createdCustomers = await service.createCustomers(data)

packages/core/core-flows/src/customer/steps/delete-addresses.ts

@@ -2,13 +2,18 @@ import { ICustomerModuleService } from "@medusajs/framework/types"
 import { Modules } from "@medusajs/framework/utils"
 import { createStep, StepResponse } from "@medusajs/framework/workflows-sdk"
 
+/**
+ * The IDs of the customer addresses to delete.
+ */
+export type DeleteCustomerAddressesStepInput = string[]
+
 export const deleteCustomerAddressesStepId = "delete-customer-addresses"
 /**
  * This step deletes one or more customer addresses.
  */
 export const deleteCustomerAddressesStep = createStep(
   deleteCustomerAddressesStepId,
-  async (ids: string[], { container }) => {
+  async (ids: DeleteCustomerAddressesStepInput, { container }) => {
     const service = container.resolve<ICustomerModuleService>(Modules.CUSTOMER)
 
     const existing = await service.listCustomerAddresses({

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

@@ -2,13 +2,18 @@ import { ICustomerModuleService } from "@medusajs/framework/types"
 import { Modules } from "@medusajs/framework/utils"
 import { createStep, StepResponse } from "@medusajs/framework/workflows-sdk"
 
+/**
+ * The IDs of the customers to delete.
+ */
+export type DeleteCustomersStepInput = string[]
+
 export const deleteCustomersStepId = "delete-customers"
 /**
  * This step deletes one or more customers.
  */
 export const deleteCustomersStep = createStep(
   deleteCustomersStepId,
-  async (ids: string[], { container }) => {
+  async (ids: DeleteCustomersStepInput, { container }) => {
     const service = container.resolve<ICustomerModuleService>(Modules.CUSTOMER)
 
     await service.softDeleteCustomers(ids)

packages/core/core-flows/src/customer/steps/index.ts

@@ -6,3 +6,4 @@ export * from "./update-addresses"
 export * from "./delete-addresses"
 export * from "./maybe-unset-default-billing-addresses"
 export * from "./maybe-unset-default-shipping-addresses"
+export * from "./validate-customer-account-creation"

packages/core/core-flows/src/customer/steps/maybe-unset-default-billing-addresses.ts

@@ -8,10 +8,29 @@ import { Modules, isDefined } from "@medusajs/framework/utils"
 import { createStep } from "@medusajs/framework/workflows-sdk"
 import { unsetForCreate, unsetForUpdate } from "./utils"
 
+/**
+ * The addresses being created or updated.
+ */
 export type MaybeUnsetDefaultBillingAddressStepInput = {
+  /**
+   * The addresses being created. If the address has 
+   * the `is_default_billing` property set to `true`,
+   * the existing default billing address of the customer will be unset.
+   */
   create?: CreateCustomerAddressDTO[]
+  /**
+   * The addresses being updated.
+   */
   update?: {
+    /**
+     * The selector to identify the customers to unset their default billing address.
+     */
     selector: FilterableCustomerAddressProps
+    /**
+     * The address details to update. The `is_default_billing` property
+     * of existing customer addresses are only unset if 
+     * the `is_default_billing` property in this object is set to `true`.
+     */
     update: UpdateCustomerAddressDTO
   }
 }
@@ -19,7 +38,31 @@ export type MaybeUnsetDefaultBillingAddressStepInput = {
 export const maybeUnsetDefaultBillingAddressesStepId =
   "maybe-unset-default-billing-customer-addresses"
 /**
- * This step unsets the `is_default_billing` property of one or more addresses.
+ * This step unsets the `is_default_billing` property of existing customer addresses
+ * if the `is_default_billing` property in the addresses in the input is set to `true`.
+ * 
+ * @example
+ * const data = maybeUnsetDefaultBillingAddressesStep({
+ *   create: [{
+ *     customer_id: "cus_123",
+ *     first_name: "John",
+ *     last_name: "Doe",
+ *     address_1: "123 Main St",
+ *     city: "Anytown",
+ *     country_code: "US",
+ *     postal_code: "12345",
+ *     phone: "555-555-5555"
+ *     is_default_billing: true
+ *   }],
+ *   update: {
+ *     selector: {
+ *       customer_id: "cus_123"
+ *     },
+ *     update: {
+ *       is_default_billing: true
+ *     }
+ *   }
+ * })
  */
 export const maybeUnsetDefaultBillingAddressesStep = createStep(
   maybeUnsetDefaultBillingAddressesStepId,

packages/core/core-flows/src/customer/steps/maybe-unset-default-shipping-addresses.ts

@@ -8,10 +8,29 @@ import { Modules, isDefined } from "@medusajs/framework/utils"
 import { createStep } from "@medusajs/framework/workflows-sdk"
 import { unsetForCreate, unsetForUpdate } from "./utils"
 
+/**
+ * The addresses being created or updated.
+ */
 export type MaybeUnsetDefaultShippingAddressesStepInput = {
+  /**
+   * The addresses being created. If the address has
+   * the `is_default_shipping` property set to `true`,
+   * the existing default shipping address of the customer will be unset.
+   */
   create?: CreateCustomerAddressDTO[]
+  /**
+   * The addresses being updated.
+   */
   update?: {
+    /**
+     * The selector to identify the customers to unset their default shipping address.
+     */
     selector: FilterableCustomerAddressProps
+    /**
+     * The address details to update. The `is_default_shipping` property
+     * of existing customer addresses are only unset if
+     * the `is_default_shipping` property in this object is set to `true`.
+     */
     update: UpdateCustomerAddressDTO
   }
 }
@@ -19,7 +38,31 @@ export type MaybeUnsetDefaultShippingAddressesStepInput = {
 export const maybeUnsetDefaultShippingAddressesStepId =
   "maybe-unset-default-shipping-customer-addresses"
 /**
- * This step unsets the `is_default_shipping` property of one or more addresses.
+ * This step unsets the `is_default_billing` property of existing customer addresses
+ * if the `is_default_billing` property in the addresses in the input is set to `true`.
+ * 
+ * @example
+ * const data = maybeUnsetDefaultShippingAddressesStep({
+ *   create: [{
+ *     customer_id: "cus_123",
+ *     first_name: "John",
+ *     last_name: "Doe",
+ *     address_1: "123 Main St",
+ *     city: "Anytown",
+ *     country_code: "US",
+ *     postal_code: "12345",
+ *     phone: "555-555-5555",
+ *     is_default_shipping: true
+ *   }],
+ *   update: {
+ *     selector: {
+ *       customer_id: "cus_123"
+ *     },
+ *     update: {
+ *       is_default_shipping: true
+ *     }
+ *   }
+ * })
  */
 export const maybeUnsetDefaultShippingAddressesStep = createStep(
   maybeUnsetDefaultShippingAddressesStepId,

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

@@ -10,14 +10,33 @@ import {
 } from "@medusajs/framework/utils"
 import { StepResponse, createStep } from "@medusajs/framework/workflows-sdk"
 
+/**
+ * The data to update one or more customer addresses.
+ */
 export type UpdateCustomerAddresseStepInput = {
+  /**
+   * The filters to select the customer addresses to update.
+   */
   selector: FilterableCustomerAddressProps
+  /**
+   * The data to update the customer addresses with.
+   */
   update: UpdateCustomerAddressDTO
 }
 
 export const updateCustomerAddresseStepId = "update-customer-addresses"
 /**
  * This step updates one or more customer addresses.
+ * 
+ * @example
+ * const data = updateCustomerAddressesStep({
+ *   selector: {
+ *     customer_id: "cus_123"
+ *   },
+ *   update: {
+ *     country_code: "us"
+ *   }
+ * })
  */
 export const updateCustomerAddressesStep = createStep(
   updateCustomerAddresseStepId,

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

@@ -10,14 +10,33 @@ import {
 } from "@medusajs/framework/utils"
 import { StepResponse, createStep } from "@medusajs/framework/workflows-sdk"
 
+/**
+ * The data to update one or more customers.
+ */
 export type UpdateCustomersStepInput = {
+  /**
+   * The filters to select the customers to update.
+   */
   selector: FilterableCustomerProps
+  /**
+   * The data to update the customers with.
+   */
   update: CustomerUpdatableFields
 }
 
 export const updateCustomersStepId = "update-customer"
 /**
  * This step updates one or more customers.
+ * 
+ * @example
+ * const data = updateCustomersStep({
+ *   selector: {
+ *     id: "cus_123"
+ *   },
+ *   update: {
+ *     last_name: "Doe"
+ *   }
+ * })
  */
 export const updateCustomersStep = createStep(
   updateCustomersStepId,

packages/core/core-flows/src/customer/steps/validate-customer-account-creation.ts

@@ -5,6 +5,24 @@ import { CreateCustomerAccountWorkflowInput } from "../workflows"
 export const validateCustomerAccountCreationStepId =
   "validate-customer-account-creation"
 
+/**
+ * This step validates the input data for creating a customer account.
+ * The step throws an error if:
+ * 
+ * - The email is missing
+ * - A customer with the email already exists and has an account
+ * - A guest customer with the email already exists
+ * 
+ * @example
+ * const data = validateCustomerAccountCreation({
+ *   authIdentityId: "au_1234",
+ *   customerData: {
+ *     first_name: "John",
+ *     last_name: "Doe",
+ *     email: "john.doe@example.com",
+ *   }
+ * })
+ */
 export const validateCustomerAccountCreation = createStep(
   validateCustomerAccountCreationStepId,
   async (input: CreateCustomerAccountWorkflowInput, { container }) => {

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

@@ -9,14 +9,47 @@ import { setAuthAppMetadataStep } from "../../auth"
 import { validateCustomerAccountCreation } from "../steps/validate-customer-account-creation"
 import { createCustomersWorkflow } from "./create-customers"
 
+/**
+ * The details of the customer account to create.
+ */
 export type CreateCustomerAccountWorkflowInput = {
+  /**
+   * The ID of the auth identity to attach the customer to.
+   */
   authIdentityId: string
+  /**
+   * The details of the customer to create.
+   */
   customerData: CreateCustomerDTO
 }
 
 export const createCustomerAccountWorkflowId = "create-customer-account"
 /**
- * This workflow creates an authentication account for a customer.
+ * This workflow creates a customer and attaches it to an auth identity. It's used by the
+ * [Register Customer Store API Route](https://docs.medusajs.com/api/store#customers_postcustomers).
+ * 
+ * You can create an auth identity first using the [Retrieve Registration JWT Token API Route](https://docs.medusajs.com/api/store#auth_postactor_typeauth_provider_register).
+ * Learn more about basic authentication flows in [this documentation](https://docs.medusajs.com/resources/commerce-modules/auth/authentication-route).
+ * 
+ * You can use this workflow within your customizations or your own custom workflows, allowing you to 
+ * register or create customer accounts within your custom flows.
+ * 
+ * @example
+ * const { result } = await createCustomerAccountWorkflow(container)
+ * .run({
+ *   input: {
+ *     authIdentityId: "au_1234",
+ *     customerData: {
+ *       first_name: "John",
+ *       last_name: "Doe",
+ *       email: "john.doe@example.com",
+ *     }
+ *   }
+ * })
+ * 
+ * @summary
+ * 
+ * Create or register a customer account.
  */
 export const createCustomerAccountWorkflow = createWorkflow(
   createCustomerAccountWorkflowId,

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

@@ -6,11 +6,48 @@ import {
 } from "@medusajs/framework/workflows-sdk"
 import { deleteCustomerAddressesStep } from "../steps"
 
-export type DeleteCustomerAddressesWorkflowInput = { ids: string[] }
+/**
+ * The details of the addresses to delete.
+ */
+export type DeleteCustomerAddressesWorkflowInput = { 
+  /**
+   * The IDs of the addresses to delete.
+   */
+  ids: string[]
+}
 
 export const deleteCustomerAddressesWorkflowId = "delete-customer-addresses"
 /**
- * This workflow deletes one or more customer addresses.
+ * This workflow deletes one or more customer addresses. It's used by the
+ * [Remove Customer Addresses Admin API Route](https://docs.medusajs.com/api/admin#customers_deletecustomersidaddressesaddress_id)
+ * and the [Remove Customer Addresses Store API Route](https://docs.medusajs.com/api/store#customers_deletecustomersmeaddressesaddress_id).
+ * 
+ * :::note
+ * 
+ * This workflow deletes addresses created by the [Customer Module](https://docs.medusajs.com/resources/commerce-modules/customer)
+ * only. So, you can't delete addresses attached to a cart, for example. To do that, use the workflow
+ * relevant to that module.
+ * 
+ * :::
+ * 
+ * You can use this workflow within your customizations or your own custom workflows, allowing you to 
+ * delete customer addresses in your custom flows.
+ * 
+ * @example
+ * const { result } = await deleteCustomerAddressesWorkflow(container)
+ * .run({
+ *   input: {
+ *     ids: [
+ *       "cuaddress_123"
+ *     ]
+ *   }
+ * })
+ * 
+ * @summary
+ * 
+ * Delete one or more customer addresses.
+ * 
+ * @property hooks.addressesDeleted - This hook is executed after the addresses are deleted. You can consume this hook to perform custom actions.
  */
 export const deleteCustomerAddressesWorkflow = createWorkflow(
   deleteCustomerAddressesWorkflowId,

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

@@ -9,11 +9,39 @@ import {
 import { emitEventStep } from "../../common/steps/emit-event"
 import { deleteCustomersStep } from "../steps"
 
-export type DeleteCustomersWorkflowInput = { ids: string[] }
+/**
+ * The details of the customers to delete.
+ */
+export type DeleteCustomersWorkflowInput = { 
+  /**
+   * The IDs of the customers to delete.
+   */
+  ids: string[]
+}
 
 export const deleteCustomersWorkflowId = "delete-customers"
 /**
- * This workflow deletes one or more customers.
+ * This workflow deletes one or more customers. It's used by the 
+ * {@link removeCustomerAccountWorkflow}.
+ * 
+ * You can use this workflow within your customizations or your own custom workflows, allowing you to 
+ * delete customers in your custom flows.
+ * 
+ * @example
+ * const { result } = await deleteCustomersWorkflow(container)
+ * .run({
+ *   input: {
+ *     ids: [
+ *       "cus_123",
+ *     ]
+ *   }
+ * })
+ * 
+ * @summary
+ * 
+ * Delete one or more customers.
+ * 
+ * @property hooks.customersDeleted - This hook is executed after the customers are deleted. You can consume this hook to perform custom actions.
  */
 export const deleteCustomersWorkflow = createWorkflow(
   deleteCustomersWorkflowId,

packages/core/core-flows/src/customer/workflows/remove-customer-account.ts

@@ -15,7 +15,30 @@ export type RemoveCustomerAccountWorkflowInput = {
 }
 export const removeCustomerAccountWorkflowId = "remove-customer-account"
 /**
- * This workflow deletes a user and remove the association in the auth identity.
+ * This workflow deletes a customer and remove its association to its auth identity. It's used by the
+ * [Delete Customer Admin API Route](https://docs.medusajs.com/api/admin#customers_deletecustomersid).
+ * 
+ * You can use this workflow within your customizations or your own custom workflows, allowing you to
+ * delete customer accounts within your custom flows.
+ * 
+ * :::note
+ * 
+ * This workflow uses the {@link deleteCustomersWorkflow} which has a hook that allows you to perform 
+ * custom actions after the customers are deleted.
+ * 
+ * :::
+ * 
+ * @example
+ * const { result } = await removeCustomerAccountWorkflow(container)
+ * .run({
+ *   input: {
+ *     customerId: "cus_123"
+ *   }
+ * })
+ * 
+ * @summary
+ * 
+ * Delete a customer account and its auth identity association.
  */
 export const removeCustomerAccountWorkflow = createWorkflow(
   removeCustomerAccountWorkflowId,