From b79dc40bc9725eb9cde3feb43b8f6d018c6aa95a Mon Sep 17 00:00:00 2001 From: Shahed Nasser Date: Thu, 16 Jan 2025 15:29:59 +0200 Subject: [PATCH] chore(core-flows): improve TSDocs of customer and customer groups workflows / steps (#10993) * improve customer tsdocs * finished improving tsdocs * fix build error --- .../workflows/add-shipping-method-to-cart.ts | 2 + .../src/cart/workflows/add-to-cart.ts | 2 + .../src/cart/workflows/complete-cart.ts | 2 + .../src/cart/workflows/create-carts.ts | 2 +- .../src/cart/workflows/refresh-cart-items.ts | 2 + .../refresh-cart-shipping-methods.ts | 2 + .../workflows/refresh-payment-collection.ts | 2 + .../cart/workflows/transfer-cart-customer.ts | 2 + .../cart/workflows/update-cart-promotions.ts | 2 + .../src/cart/workflows/update-cart.ts | 2 +- .../workflows/update-line-item-in-cart.ts | 2 + .../steps/create-customer-groups.ts | 7 ++- .../steps/delete-customer-groups.ts | 7 ++- .../steps/link-customer-groups-customer.ts | 9 +++- .../steps/link-customers-customer-group.ts | 9 +++- .../steps/update-customer-groups.ts | 19 ++++++++ .../workflows/create-customer-groups.ts | 36 ++++++++++++++- .../workflows/delete-customer-groups.ts | 28 +++++++++++- .../link-customer-groups-customer.ts | 31 ++++++++++++- .../link-customers-customer-group.ts | 31 ++++++++++++- .../workflows/update-customer-groups.ts | 39 +++++++++++++++- .../src/customer/steps/create-addresses.ts | 21 ++++++++- .../src/customer/steps/create-customers.ts | 16 ++++++- .../src/customer/steps/delete-addresses.ts | 7 ++- .../src/customer/steps/delete-customers.ts | 7 ++- .../core-flows/src/customer/steps/index.ts | 1 + .../maybe-unset-default-billing-addresses.ts | 45 ++++++++++++++++++- .../maybe-unset-default-shipping-addresses.ts | 45 ++++++++++++++++++- .../src/customer/steps/update-addresses.ts | 19 ++++++++ .../src/customer/steps/update-customers.ts | 19 ++++++++ .../validate-customer-account-creation.ts | 18 ++++++++ .../workflows/create-customer-account.ts | 35 ++++++++++++++- .../customer/workflows/delete-addresses.ts | 41 ++++++++++++++++- .../customer/workflows/delete-customers.ts | 32 ++++++++++++- .../workflows/remove-customer-account.ts | 25 ++++++++++- 35 files changed, 541 insertions(+), 28 deletions(-) diff --git a/packages/core/core-flows/src/cart/workflows/add-shipping-method-to-cart.ts b/packages/core/core-flows/src/cart/workflows/add-shipping-method-to-cart.ts index 84374ddfda..f16cab4781 100644 --- a/packages/core/core-flows/src/cart/workflows/add-shipping-method-to-cart.ts +++ b/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, diff --git a/packages/core/core-flows/src/cart/workflows/add-to-cart.ts b/packages/core/core-flows/src/cart/workflows/add-to-cart.ts index 644a9e9f5e..6bce74e49d 100644 --- a/packages/core/core-flows/src/cart/workflows/add-to-cart.ts +++ b/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, diff --git a/packages/core/core-flows/src/cart/workflows/complete-cart.ts b/packages/core/core-flows/src/cart/workflows/complete-cart.ts index c7315190dc..0bcaefa3f3 100644 --- a/packages/core/core-flows/src/cart/workflows/complete-cart.ts +++ b/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( { diff --git a/packages/core/core-flows/src/cart/workflows/create-carts.ts b/packages/core/core-flows/src/cart/workflows/create-carts.ts index a83310906b..16f166644c 100644 --- a/packages/core/core-flows/src/cart/workflows/create-carts.ts +++ b/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( diff --git a/packages/core/core-flows/src/cart/workflows/refresh-cart-items.ts b/packages/core/core-flows/src/cart/workflows/refresh-cart-items.ts index 30b09a154d..6dec0d0925 100644 --- a/packages/core/core-flows/src/cart/workflows/refresh-cart-items.ts +++ b/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, diff --git a/packages/core/core-flows/src/cart/workflows/refresh-cart-shipping-methods.ts b/packages/core/core-flows/src/cart/workflows/refresh-cart-shipping-methods.ts index 235c50f91a..55f68141c6 100644 --- a/packages/core/core-flows/src/cart/workflows/refresh-cart-shipping-methods.ts +++ b/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, diff --git a/packages/core/core-flows/src/cart/workflows/refresh-payment-collection.ts b/packages/core/core-flows/src/cart/workflows/refresh-payment-collection.ts index 9bae6a66cb..66dccb8be8 100644 --- a/packages/core/core-flows/src/cart/workflows/refresh-payment-collection.ts +++ b/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, diff --git a/packages/core/core-flows/src/cart/workflows/transfer-cart-customer.ts b/packages/core/core-flows/src/cart/workflows/transfer-cart-customer.ts index 9349b7e759..975192744a 100644 --- a/packages/core/core-flows/src/cart/workflows/transfer-cart-customer.ts +++ b/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, diff --git a/packages/core/core-flows/src/cart/workflows/update-cart-promotions.ts b/packages/core/core-flows/src/cart/workflows/update-cart-promotions.ts index d5d3ec6608..3c8fb37d31 100644 --- a/packages/core/core-flows/src/cart/workflows/update-cart-promotions.ts +++ b/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, diff --git a/packages/core/core-flows/src/cart/workflows/update-cart.ts b/packages/core/core-flows/src/cart/workflows/update-cart.ts index baeea6ce19..dc648045fe 100644 --- a/packages/core/core-flows/src/cart/workflows/update-cart.ts +++ b/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( diff --git a/packages/core/core-flows/src/cart/workflows/update-line-item-in-cart.ts b/packages/core/core-flows/src/cart/workflows/update-line-item-in-cart.ts index d5c382cbed..101b38093d 100644 --- a/packages/core/core-flows/src/cart/workflows/update-line-item-in-cart.ts +++ b/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, diff --git a/packages/core/core-flows/src/customer-group/steps/create-customer-groups.ts b/packages/core/core-flows/src/customer-group/steps/create-customer-groups.ts index 9f51aade80..1b0dd3ed92 100644 --- a/packages/core/core-flows/src/customer-group/steps/create-customer-groups.ts +++ b/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(Modules.CUSTOMER) const createdCustomerGroups = await service.createCustomerGroups(data) diff --git a/packages/core/core-flows/src/customer-group/steps/delete-customer-groups.ts b/packages/core/core-flows/src/customer-group/steps/delete-customer-groups.ts index c8d8522920..108dc7663f 100644 --- a/packages/core/core-flows/src/customer-group/steps/delete-customer-groups.ts +++ b/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(Modules.CUSTOMER) await service.softDeleteCustomerGroups(ids) diff --git a/packages/core/core-flows/src/customer-group/steps/link-customer-groups-customer.ts b/packages/core/core-flows/src/customer-group/steps/link-customer-groups-customer.ts index 486cfd34e5..b78294874c 100644 --- a/packages/core/core-flows/src/customer-group/steps/link-customer-groups-customer.ts +++ b/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, diff --git a/packages/core/core-flows/src/customer-group/steps/link-customers-customer-group.ts b/packages/core/core-flows/src/customer-group/steps/link-customers-customer-group.ts index 65dbdbbb1f..0eb017bd85 100644 --- a/packages/core/core-flows/src/customer-group/steps/link-customers-customer-group.ts +++ b/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, diff --git a/packages/core/core-flows/src/customer-group/steps/update-customer-groups.ts b/packages/core/core-flows/src/customer-group/steps/update-customer-groups.ts index 613b3c67ca..6541620394 100644 --- a/packages/core/core-flows/src/customer-group/steps/update-customer-groups.ts +++ b/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, diff --git a/packages/core/core-flows/src/customer-group/workflows/create-customer-groups.ts b/packages/core/core-flows/src/customer-group/workflows/create-customer-groups.ts index 1a71ab978c..b24347e7d8 100644 --- a/packages/core/core-flows/src/customer-group/workflows/create-customer-groups.ts +++ b/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 - ): WorkflowResponse => { + ): WorkflowResponse => { return new WorkflowResponse(createCustomerGroupsStep(input.customersData)) } ) diff --git a/packages/core/core-flows/src/customer-group/workflows/delete-customer-groups.ts b/packages/core/core-flows/src/customer-group/workflows/delete-customer-groups.ts index fbf4381f26..1d4a4532d0 100644 --- a/packages/core/core-flows/src/customer-group/workflows/delete-customer-groups.ts +++ b/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, diff --git a/packages/core/core-flows/src/customer-group/workflows/link-customer-groups-customer.ts b/packages/core/core-flows/src/customer-group/workflows/link-customer-groups-customer.ts index a72b3e91ad..d5ff021afb 100644 --- a/packages/core/core-flows/src/customer-group/workflows/link-customer-groups-customer.ts +++ b/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): WorkflowData => { + (input: WorkflowData): WorkflowData => { return linkCustomerGroupsToCustomerStep(input) } ) diff --git a/packages/core/core-flows/src/customer-group/workflows/link-customers-customer-group.ts b/packages/core/core-flows/src/customer-group/workflows/link-customers-customer-group.ts index 83c1622d20..ae5068d6f2 100644 --- a/packages/core/core-flows/src/customer-group/workflows/link-customers-customer-group.ts +++ b/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): WorkflowData => { + (input: WorkflowData): WorkflowData => { return linkCustomersToCustomerGroupStep(input) } ) diff --git a/packages/core/core-flows/src/customer-group/workflows/update-customer-groups.ts b/packages/core/core-flows/src/customer-group/workflows/update-customer-groups.ts index e60fd3e5a2..6b13914741 100644 --- a/packages/core/core-flows/src/customer-group/workflows/update-customer-groups.ts +++ b/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 - ): WorkflowResponse => { + ): WorkflowResponse => { return new WorkflowResponse(updateCustomerGroupsStep(input)) } ) diff --git a/packages/core/core-flows/src/customer/steps/create-addresses.ts b/packages/core/core-flows/src/customer/steps/create-addresses.ts index 3ded197428..ebd5255c63 100644 --- a/packages/core/core-flows/src/customer/steps/create-addresses.ts +++ b/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(Modules.CUSTOMER) const addresses = await service.createCustomerAddresses(data) diff --git a/packages/core/core-flows/src/customer/steps/create-customers.ts b/packages/core/core-flows/src/customer/steps/create-customers.ts index 9a634fe152..d6858d348e 100644 --- a/packages/core/core-flows/src/customer/steps/create-customers.ts +++ b/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(Modules.CUSTOMER) const createdCustomers = await service.createCustomers(data) diff --git a/packages/core/core-flows/src/customer/steps/delete-addresses.ts b/packages/core/core-flows/src/customer/steps/delete-addresses.ts index c6c4970b03..412dfdc7d1 100644 --- a/packages/core/core-flows/src/customer/steps/delete-addresses.ts +++ b/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(Modules.CUSTOMER) const existing = await service.listCustomerAddresses({ diff --git a/packages/core/core-flows/src/customer/steps/delete-customers.ts b/packages/core/core-flows/src/customer/steps/delete-customers.ts index 0fe5b75b72..cdd9068330 100644 --- a/packages/core/core-flows/src/customer/steps/delete-customers.ts +++ b/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(Modules.CUSTOMER) await service.softDeleteCustomers(ids) diff --git a/packages/core/core-flows/src/customer/steps/index.ts b/packages/core/core-flows/src/customer/steps/index.ts index 00a01f8281..041c901307 100644 --- a/packages/core/core-flows/src/customer/steps/index.ts +++ b/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" \ No newline at end of file diff --git a/packages/core/core-flows/src/customer/steps/maybe-unset-default-billing-addresses.ts b/packages/core/core-flows/src/customer/steps/maybe-unset-default-billing-addresses.ts index c4cbdd4438..dae348cd88 100644 --- a/packages/core/core-flows/src/customer/steps/maybe-unset-default-billing-addresses.ts +++ b/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, diff --git a/packages/core/core-flows/src/customer/steps/maybe-unset-default-shipping-addresses.ts b/packages/core/core-flows/src/customer/steps/maybe-unset-default-shipping-addresses.ts index fdd65c217e..bf76baaf3f 100644 --- a/packages/core/core-flows/src/customer/steps/maybe-unset-default-shipping-addresses.ts +++ b/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, diff --git a/packages/core/core-flows/src/customer/steps/update-addresses.ts b/packages/core/core-flows/src/customer/steps/update-addresses.ts index 8a4b5be9f3..72a638786e 100644 --- a/packages/core/core-flows/src/customer/steps/update-addresses.ts +++ b/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, diff --git a/packages/core/core-flows/src/customer/steps/update-customers.ts b/packages/core/core-flows/src/customer/steps/update-customers.ts index ed6aadeeed..ebdf6f5aa1 100644 --- a/packages/core/core-flows/src/customer/steps/update-customers.ts +++ b/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, diff --git a/packages/core/core-flows/src/customer/steps/validate-customer-account-creation.ts b/packages/core/core-flows/src/customer/steps/validate-customer-account-creation.ts index 5148d3805a..59f39d9e4c 100644 --- a/packages/core/core-flows/src/customer/steps/validate-customer-account-creation.ts +++ b/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 }) => { diff --git a/packages/core/core-flows/src/customer/workflows/create-customer-account.ts b/packages/core/core-flows/src/customer/workflows/create-customer-account.ts index 4996f6bc69..8ba2696b39 100644 --- a/packages/core/core-flows/src/customer/workflows/create-customer-account.ts +++ b/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, diff --git a/packages/core/core-flows/src/customer/workflows/delete-addresses.ts b/packages/core/core-flows/src/customer/workflows/delete-addresses.ts index aeab9235aa..50ef5ae9c5 100644 --- a/packages/core/core-flows/src/customer/workflows/delete-addresses.ts +++ b/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, diff --git a/packages/core/core-flows/src/customer/workflows/delete-customers.ts b/packages/core/core-flows/src/customer/workflows/delete-customers.ts index ea31eed7f8..1e77f2aa5e 100644 --- a/packages/core/core-flows/src/customer/workflows/delete-customers.ts +++ b/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, diff --git a/packages/core/core-flows/src/customer/workflows/remove-customer-account.ts b/packages/core/core-flows/src/customer/workflows/remove-customer-account.ts index ec1c252d7e..b05367ce6f 100644 --- a/packages/core/core-flows/src/customer/workflows/remove-customer-account.ts +++ b/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,