diff --git a/.changeset/gorgeous-comics-compete.md b/.changeset/gorgeous-comics-compete.md new file mode 100644 index 0000000000000..08d9aa19f95b2 --- /dev/null +++ b/.changeset/gorgeous-comics-compete.md @@ -0,0 +1,5 @@ +--- +"@medusajs/core-flows": patch +--- + +fix(core-flows): process payment capture condition diff --git a/.changeset/six-bears-vanish.md b/.changeset/six-bears-vanish.md new file mode 100644 index 0000000000000..9524dd0b1bca6 --- /dev/null +++ b/.changeset/six-bears-vanish.md @@ -0,0 +1,7 @@ +--- +"@medusajs/medusa": patch +"@medusajs/framework": patch +"@medusajs/cli": patch +--- + +feat(core, medusa, cli): Enable migration scripts diff --git a/.changeset/weak-poems-run.md b/.changeset/weak-poems-run.md new file mode 100644 index 0000000000000..40ca7dbabe7ce --- /dev/null +++ b/.changeset/weak-poems-run.md @@ -0,0 +1,6 @@ +--- +"@medusajs/icons": patch +"@medusajs/dashboard": patch +--- + +chore(icons,dashboard): Pull latest icons and update branch icon in category tree diff --git a/.github/workflows/test-cli-with-database.yml b/.github/workflows/test-cli-with-database.yml index 07080d0b91d76..e52808e7657bd 100644 --- a/.github/workflows/test-cli-with-database.yml +++ b/.github/workflows/test-cli-with-database.yml @@ -47,7 +47,7 @@ jobs: node-version: 20 - name: Install Medusa cli - run: npm i -g @medusajs/cli@preview + run: npm i -g @medusajs/cli@latest - name: Create Medusa project run: | @@ -59,22 +59,22 @@ jobs: working-directory: ../cli-test - name: Run migrations - run: medusa db:migrate + run: npx medusa db:migrate working-directory: ../cli-test - name: Create admin user - run: medusa user -e test@test.com -p password -i admin_123 + run: npx medusa user -e test@test.com -p password -i admin_123 working-directory: ../cli-test - name: Run development server - run: medusa develop & + run: npx medusa develop & working-directory: ../cli-test - name: Testing development server uses: ./.github/actions/test-server - name: Starting medusa - run: medusa start & + run: npx medusa start & working-directory: ../cli-test - name: Testing server diff --git a/packages/admin/dashboard/src/components/common/sortable-tree/tree-item.tsx b/packages/admin/dashboard/src/components/common/sortable-tree/tree-item.tsx index 1e455df24629d..1516e68a42deb 100644 --- a/packages/admin/dashboard/src/components/common/sortable-tree/tree-item.tsx +++ b/packages/admin/dashboard/src/components/common/sortable-tree/tree-item.tsx @@ -4,7 +4,7 @@ import { DotsSix, FolderIllustration, FolderOpenIllustration, - Swatch, + TagIllustration, TriangleRightMini, } from "@medusajs/icons" import { Badge, clx, IconButton } from "@medusajs/ui" @@ -136,7 +136,7 @@ const Icon = ({ childrenCount, collapsed, clone }: IconProps) => { ) ) : ( - + )} ) diff --git a/packages/cli/medusa-cli/src/create-cli.ts b/packages/cli/medusa-cli/src/create-cli.ts index 2f3a1b42e29a0..4c26cf50be970 100644 --- a/packages/cli/medusa-cli/src/create-cli.ts +++ b/packages/cli/medusa-cli/src/create-cli.ts @@ -178,6 +178,10 @@ function buildLocalCommands(cli, isLocalProject) { command: "db:migrate", desc: "Migrate the database by executing pending migrations", builder: (builder) => { + builder.option("skip-scripts", { + type: "boolean", + describe: "Do not run migration scripts", + }) builder.option("skip-links", { type: "boolean", describe: "Do not sync links", 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 3aae1f6c96ba1..1d35a332219ba 100644 --- a/packages/core/core-flows/src/cart/workflows/create-carts.ts +++ b/packages/core/core-flows/src/cart/workflows/create-carts.ts @@ -48,7 +48,7 @@ export const createCartWorkflowId = "create-cart" * * This workflow has a hook that allows you to perform custom actions on the created cart. You can see an example in [this guide](https://docs.medusajs.com/resources/commerce-modules/cart/extend#step-4-consume-cartcreated-workflow-hook). * - * You can also use this workflow within your own custom workflows, allowing you to wrap custom logic around cart creation. + * You can also use this workflow within your customizations or your own custom workflows, allowing you to wrap custom logic around cart creation. * * @example * const { result } = await createCartWorkflow(container) 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 569692ea43838..325697bfeeb7f 100644 --- a/packages/core/core-flows/src/cart/workflows/update-cart.ts +++ b/packages/core/core-flows/src/cart/workflows/update-cart.ts @@ -48,7 +48,7 @@ export const updateCartWorkflowId = "update-cart" * This workflow has a hook that allows you to perform custom actions on the updated cart. For example, you can pass custom data under the `additional_data` property of the Update Cart API route, * then update any associated details related to the cart in the workflow's hook. * - * You can also use this workflow within your own custom workflows, allowing you to wrap custom logic around updating a cart. + * You can also use this workflow within your customizations or your own custom workflows, allowing you to wrap custom logic around updating a cart. * * @example * const { result } = await updateCartWorkflow(container) diff --git a/packages/core/core-flows/src/customer/workflows/create-addresses.ts b/packages/core/core-flows/src/customer/workflows/create-addresses.ts index a51e8f9b61ca6..322eb1f10e5b9 100644 --- a/packages/core/core-flows/src/customer/workflows/create-addresses.ts +++ b/packages/core/core-flows/src/customer/workflows/create-addresses.ts @@ -33,7 +33,7 @@ export const createCustomerAddressesWorkflowId = "create-customer-addresses" * This workflow has a hook that allows you to perform custom actions on the created customer addresses. For example, you can pass under `additional_data` custom data that * allows you to create custom data models linked to the addresses. * - * You can also use this workflow within your own custom workflows, allowing you to wrap custom logic around creating customer addresses. + * You can also use this workflow within your customizations or your own custom workflows, allowing you to wrap custom logic around creating customer addresses. * * @example * const { result } = await createCustomerAddressesWorkflow(container) diff --git a/packages/core/core-flows/src/customer/workflows/create-customers.ts b/packages/core/core-flows/src/customer/workflows/create-customers.ts index dc2b167f3d561..ac8d3448fb6d2 100644 --- a/packages/core/core-flows/src/customer/workflows/create-customers.ts +++ b/packages/core/core-flows/src/customer/workflows/create-customers.ts @@ -25,7 +25,7 @@ export const createCustomersWorkflowId = "create-customers" * * This workflow has a hook that allows you to perform custom actions on the created customer. You can see an example in [this guide](https://docs.medusajs.com/resources/commerce-modules/customer/extend). * - * You can also use this workflow within your own custom workflows, allowing you to wrap custom logic around creating customers. + * You can also use this workflow within your customizations or your own custom workflows, allowing you to wrap custom logic around creating customers. * * @example * const { result } = await createCustomersWorkflow(container) diff --git a/packages/core/core-flows/src/customer/workflows/update-addresses.ts b/packages/core/core-flows/src/customer/workflows/update-addresses.ts index 978fe51a2dc44..c5c618092aabd 100644 --- a/packages/core/core-flows/src/customer/workflows/update-addresses.ts +++ b/packages/core/core-flows/src/customer/workflows/update-addresses.ts @@ -38,7 +38,7 @@ export const updateCustomerAddressesWorkflowId = "update-customer-addresses" * This workflow has a hook that allows you to perform custom actions on the updated customer addresses. For example, you can pass under `additional_data` custom data that * allows you to update custom data models linked to the addresses. * - * You can also use this workflow within your own custom workflows, allowing you to wrap custom logic around updating customer addresses. + * You can also use this workflow within your customizations or your own custom workflows, allowing you to wrap custom logic around updating customer addresses. * * @example * const { result } = await updateCustomerAddressesWorkflow(container) diff --git a/packages/core/core-flows/src/customer/workflows/update-customers.ts b/packages/core/core-flows/src/customer/workflows/update-customers.ts index c789cb5b8983f..2263f81fe3958 100644 --- a/packages/core/core-flows/src/customer/workflows/update-customers.ts +++ b/packages/core/core-flows/src/customer/workflows/update-customers.ts @@ -36,7 +36,7 @@ export const updateCustomersWorkflowId = "update-customers" * This workflow has a hook that allows you to perform custom actions on the updated customer. For example, you can pass under `additional_data` custom data to update * custom data models linked to the customers. * - * You can also use this workflow within your own custom workflows, allowing you to wrap custom logic around updating customers. + * You can also use this workflow within your customizations or your own custom workflows, allowing you to wrap custom logic around updating customers. * * @example * const { result } = await updateCustomersWorkflow(container) diff --git a/packages/core/core-flows/src/order/steps/add-order-transaction.ts b/packages/core/core-flows/src/order/steps/add-order-transaction.ts index 841f5a0a1e81e..550ad4f496f00 100644 --- a/packages/core/core-flows/src/order/steps/add-order-transaction.ts +++ b/packages/core/core-flows/src/order/steps/add-order-transaction.ts @@ -2,6 +2,16 @@ import { CreateOrderTransactionDTO } from "@medusajs/framework/types" import { Modules } from "@medusajs/framework/utils" import { StepResponse, createStep } from "@medusajs/framework/workflows-sdk" +/** + * The transaction(s) to add to the order. + */ +export type AddOrderTransactionStepInput = CreateOrderTransactionDTO | CreateOrderTransactionDTO[] + +/** + * The added order transaction(s). + */ +export type AddOrderTransactionStepOutput = CreateOrderTransactionDTO | CreateOrderTransactionDTO[] + export const addOrderTransactionStepId = "add-order-transaction" /** * This step creates order transactions. @@ -9,7 +19,7 @@ export const addOrderTransactionStepId = "add-order-transaction" export const addOrderTransactionStep = createStep( addOrderTransactionStepId, async ( - data: CreateOrderTransactionDTO | CreateOrderTransactionDTO[], + data: AddOrderTransactionStepInput, { container } ) => { const service = container.resolve(Modules.ORDER) @@ -36,7 +46,7 @@ export const addOrderTransactionStep = createStep( const created = await service.addOrderTransactions(trxsData) return new StepResponse( - Array.isArray(data) ? created : created[0], + (Array.isArray(data) ? created : created[0]) as AddOrderTransactionStepOutput, created.map((c) => c.id) ) }, diff --git a/packages/core/core-flows/src/order/steps/archive-orders.ts b/packages/core/core-flows/src/order/steps/archive-orders.ts index 32cccfb27d1e0..b170da6427dad 100644 --- a/packages/core/core-flows/src/order/steps/archive-orders.ts +++ b/packages/core/core-flows/src/order/steps/archive-orders.ts @@ -2,7 +2,13 @@ import { IOrderModuleService } from "@medusajs/framework/types" import { Modules } from "@medusajs/framework/utils" import { createStep, StepResponse } from "@medusajs/framework/workflows-sdk" +/** + * The details of archiving the orders. + */ export type ArchiveOrdersStepInput = { + /** + * The IDs of the orders to archive. + */ orderIds: string[] } diff --git a/packages/core/core-flows/src/order/steps/cancel-fulfillment.ts b/packages/core/core-flows/src/order/steps/cancel-fulfillment.ts index f98e3ea72eeeb..0af1899ea5d6f 100644 --- a/packages/core/core-flows/src/order/steps/cancel-fulfillment.ts +++ b/packages/core/core-flows/src/order/steps/cancel-fulfillment.ts @@ -8,6 +8,17 @@ import { StepResponse, createStep } from "@medusajs/framework/workflows-sdk" export const cancelOrderFulfillmentStepId = "cancel-order-fulfillment" /** * This step cancels an order's fulfillment. + * + * @example + * const data = cancelOrderFulfillmentStep({ + * order_id: "order_123", + * items: [ + * { + * id: "item_123", + * quantity: 1 + * } + * ] + * }) */ export const cancelOrderFulfillmentStep = createStep( cancelOrderFulfillmentStepId, diff --git a/packages/core/core-flows/src/order/steps/cancel-orders.ts b/packages/core/core-flows/src/order/steps/cancel-orders.ts index b24715fef9b2d..4eb683e64111f 100644 --- a/packages/core/core-flows/src/order/steps/cancel-orders.ts +++ b/packages/core/core-flows/src/order/steps/cancel-orders.ts @@ -2,8 +2,17 @@ import { IOrderModuleService } from "@medusajs/framework/types" import { Modules } from "@medusajs/framework/utils" import { createStep, StepResponse } from "@medusajs/framework/workflows-sdk" +/** + * The details of canceling the orders. + */ export type CancelOrdersStepInput = { + /** + * The IDs of the orders to cancel. + */ orderIds: string[] + /** + * The ID of the user canceling the orders. + */ canceled_by?: string } diff --git a/packages/core/core-flows/src/order/steps/claim/create-claim-items-from-actions.ts b/packages/core/core-flows/src/order/steps/claim/create-claim-items-from-actions.ts index 38b274805b5e9..dc56b8d7710ee 100644 --- a/packages/core/core-flows/src/order/steps/claim/create-claim-items-from-actions.ts +++ b/packages/core/core-flows/src/order/steps/claim/create-claim-items-from-actions.ts @@ -5,13 +5,40 @@ import { import { ChangeActionType, Modules } from "@medusajs/framework/utils" import { StepResponse, createStep } from "@medusajs/framework/workflows-sdk" +/** + * The details of creating the claim items from a change action. + */ export type CreateOrderClaimItemsFromActionsInput = { + /** + * The change actions to create claim items from. + */ changes: OrderChangeActionDTO[] + /** + * The ID of the claim to create the items for. + */ claimId: string } /** * This step creates claim items from a change action. + * + * :::note + * + * You can retrieve an order change action details using [Query](https://docs.medusajs.com/learn/fundamentals/module-links/query), + * or [useQueryGraphStep](https://docs.medusajs.com/resources/references/medusa-workflows/steps/useQueryGraphStep). + * + * ::: + * + * @example + * const data = createOrderClaimItemsFromActionsStep({ + * claimId: "claim_123", + * changes: [ + * { + * id: "orchact_123", + * // other order change action details... + * } + * ] + * }) */ export const createOrderClaimItemsFromActionsStep = createStep( "create-claim-items-from-change-actions", diff --git a/packages/core/core-flows/src/order/steps/claim/delete-claims.ts b/packages/core/core-flows/src/order/steps/claim/delete-claims.ts index c33d47bfd14e1..b7d66f4e3e754 100644 --- a/packages/core/core-flows/src/order/steps/claim/delete-claims.ts +++ b/packages/core/core-flows/src/order/steps/claim/delete-claims.ts @@ -2,13 +2,23 @@ import { IOrderModuleService } from "@medusajs/framework/types" import { Modules } from "@medusajs/framework/utils" import { createStep, StepResponse } from "@medusajs/framework/workflows-sdk" +/** + * The details of deleting one or more claims. + */ +export type DeleteOrderClaimsInput = { + /** + * The IDs of the claims to delete. + */ + ids: string[] +} + export const deleteClaimsStepId = "delete-claims" /** * This step deletes one or more order claims. */ export const deleteClaimsStep = createStep( deleteClaimsStepId, - async (data: { ids: string[] }, { container }) => { + async (data: DeleteOrderClaimsInput, { container }) => { const service = container.resolve(Modules.ORDER) const deleted = await service.softDeleteOrderClaims(data.ids) diff --git a/packages/core/core-flows/src/order/steps/complete-orders.ts b/packages/core/core-flows/src/order/steps/complete-orders.ts index ab53cf6a6a2f7..55ac07e75af16 100644 --- a/packages/core/core-flows/src/order/steps/complete-orders.ts +++ b/packages/core/core-flows/src/order/steps/complete-orders.ts @@ -2,7 +2,13 @@ import { IOrderModuleService } from "@medusajs/framework/types" import { Modules } from "@medusajs/framework/utils" import { createStep, StepResponse } from "@medusajs/framework/workflows-sdk" +/** + * The details of completing the orders. + */ export type CompleteOrdersStepInput = { + /** + * The IDs of the orders to complete. + */ orderIds: string[] } diff --git a/packages/core/core-flows/src/order/steps/confirm-order-changes.ts b/packages/core/core-flows/src/order/steps/confirm-order-changes.ts index 7c2002273b449..144bcb8a1ee64 100644 --- a/packages/core/core-flows/src/order/steps/confirm-order-changes.ts +++ b/packages/core/core-flows/src/order/steps/confirm-order-changes.ts @@ -2,9 +2,21 @@ import { OrderChangeDTO } from "@medusajs/framework/types" import { Modules } from "@medusajs/framework/utils" import { createStep, StepResponse } from "@medusajs/framework/workflows-sdk" +/** + * The input for the confirm order changes step. + */ export type ConfirmOrderChangesInput = { + /** + * The ID of the order to confirm changes for. + */ orderId: string + /** + * The changes to confirm. + */ changes: OrderChangeDTO[] + /** + * The ID of the user confirming the changes. + */ confirmed_by?: string } diff --git a/packages/core/core-flows/src/order/steps/create-line-items.ts b/packages/core/core-flows/src/order/steps/create-line-items.ts index 0af1c9aca9ff6..05035524aae85 100644 --- a/packages/core/core-flows/src/order/steps/create-line-items.ts +++ b/packages/core/core-flows/src/order/steps/create-line-items.ts @@ -2,13 +2,32 @@ import { CreateOrderLineItemDTO } from "@medusajs/framework/types" import { Modules } from "@medusajs/framework/utils" import { StepResponse, createStep } from "@medusajs/framework/workflows-sdk" +/** + * The details of creating order line items. + */ export interface CreateOrderLineItemsStepInput { + /** + * The items to create. + */ items: CreateOrderLineItemDTO[] } export const createOrderLineItemsStepId = "create-order-line-items-step" /** * This step creates order line items. + * + * @example + * const data = createOrderLineItemsStep({ + * items: [ + * { + * variant_id: "variant_123", + * quantity: 1, + * unit_price: 10, + * title: "Shirt", + * order_id: "order_123" + * } + * ] + * }) */ export const createOrderLineItemsStep = createStep( createOrderLineItemsStepId, diff --git a/packages/core/core-flows/src/order/steps/create-order-shipping-methods.ts b/packages/core/core-flows/src/order/steps/create-order-shipping-methods.ts index c065e0eadafb4..1a8ea5613e98f 100644 --- a/packages/core/core-flows/src/order/steps/create-order-shipping-methods.ts +++ b/packages/core/core-flows/src/order/steps/create-order-shipping-methods.ts @@ -5,7 +5,13 @@ import { import { Modules } from "@medusajs/framework/utils" import { StepResponse, createStep } from "@medusajs/framework/workflows-sdk" +/** + * The details of creating order shipping methods. + */ export interface CreateOrderShippingMethodsStepInput { + /** + * The shipping methods to create. + */ shipping_methods: CreateOrderShippingMethodDTO[] } diff --git a/packages/core/core-flows/src/order/steps/create-orders.ts b/packages/core/core-flows/src/order/steps/create-orders.ts index 17c6b55b0af69..42259c84a1055 100644 --- a/packages/core/core-flows/src/order/steps/create-orders.ts +++ b/packages/core/core-flows/src/order/steps/create-orders.ts @@ -2,9 +2,28 @@ import { CreateOrderDTO, IOrderModuleService } from "@medusajs/framework/types" import { Modules } from "@medusajs/framework/utils" import { StepResponse, createStep } from "@medusajs/framework/workflows-sdk" +/** + * The orders to create. + */ +export type CreateOrdersStepInput = CreateOrderDTO[] + export const createOrdersStepId = "create-orders" /** * This step creates one or more orders. + * + * @example + * const data = createOrdersStep([{ + * region_id: "region_123", + * customer_id: "customer_123", + * items: [ + * { + * variant_id: "variant_123", + * quantity: 1, + * title: "Shirt", + * unit_price: 10, + * } + * ] + * }]) */ export const createOrdersStep = createStep( createOrdersStepId, diff --git a/packages/core/core-flows/src/order/steps/delete-line-items.ts b/packages/core/core-flows/src/order/steps/delete-line-items.ts index 2f60d25d55c64..5e922ae3532ca 100644 --- a/packages/core/core-flows/src/order/steps/delete-line-items.ts +++ b/packages/core/core-flows/src/order/steps/delete-line-items.ts @@ -2,7 +2,13 @@ import { IOrderModuleService } from "@medusajs/framework/types" import { Modules } from "@medusajs/framework/utils" import { StepResponse, createStep } from "@medusajs/framework/workflows-sdk" +/** + * The details of deleting order line items. + */ export interface DeleteOrderLineItemsStepInput { + /** + * The IDs of the order line items to delete. + */ ids: string[] } diff --git a/packages/core/core-flows/src/order/steps/delete-order-change-actions.ts b/packages/core/core-flows/src/order/steps/delete-order-change-actions.ts index 825776d63fc23..f43b7f552d26c 100644 --- a/packages/core/core-flows/src/order/steps/delete-order-change-actions.ts +++ b/packages/core/core-flows/src/order/steps/delete-order-change-actions.ts @@ -2,13 +2,23 @@ import { IOrderModuleService } from "@medusajs/framework/types" import { Modules } from "@medusajs/framework/utils" import { StepResponse, createStep } from "@medusajs/framework/workflows-sdk" +/** + * The details of deleting order change actions. + */ +export interface DeleteOrderChangeActionsStepInput { + /** + * The IDs of the order change actions to delete. + */ + ids: string[] +} + export const deleteOrderChangeActionsStepId = "delete-order-change-actions" /** * This step deletes order change actions. */ export const deleteOrderChangeActionsStep = createStep( deleteOrderChangeActionsStepId, - async (data: { ids: string[] }, { container }) => { + async (data: DeleteOrderChangeActionsStepInput, { container }) => { const service = container.resolve(Modules.ORDER) await service.softDeleteOrderChangeActions(data.ids) diff --git a/packages/core/core-flows/src/order/steps/delete-order-changes.ts b/packages/core/core-flows/src/order/steps/delete-order-changes.ts index 165c979475120..b18d8c6d678fa 100644 --- a/packages/core/core-flows/src/order/steps/delete-order-changes.ts +++ b/packages/core/core-flows/src/order/steps/delete-order-changes.ts @@ -2,13 +2,23 @@ import { IOrderModuleService } from "@medusajs/framework/types" import { Modules } from "@medusajs/framework/utils" import { createStep, StepResponse } from "@medusajs/framework/workflows-sdk" +/** + * The details of deleting order changes. + */ +export interface DeleteOrderChangesStepInput { + /** + * The IDs of the order changes to delete. + */ + ids: string[] +} + export const deleteOrderChangesStepId = "delete-order-change" /** * This step deletes order changes. */ export const deleteOrderChangesStep = createStep( deleteOrderChangesStepId, - async (data: { ids: string[] }, { container }) => { + async (data: DeleteOrderChangesStepInput, { container }) => { const service = container.resolve(Modules.ORDER) const deleted = await service.softDeleteOrderChanges(data.ids) diff --git a/packages/core/core-flows/src/order/steps/delete-order-shipping-methods.ts b/packages/core/core-flows/src/order/steps/delete-order-shipping-methods.ts index ffc1ac9507a8b..13c4bb0cedcd6 100644 --- a/packages/core/core-flows/src/order/steps/delete-order-shipping-methods.ts +++ b/packages/core/core-flows/src/order/steps/delete-order-shipping-methods.ts @@ -2,7 +2,13 @@ import { IOrderModuleService } from "@medusajs/framework/types" import { Modules } from "@medusajs/framework/utils" import { StepResponse, createStep } from "@medusajs/framework/workflows-sdk" +/** + * The details of deleting order shipping methods. + */ export interface DeleteOrderShippingMethodsStepInput { + /** + * The IDs of the order shipping methods to delete. + */ ids: string[] } diff --git a/packages/core/core-flows/src/order/steps/exchange/create-exchange-items-from-actions.ts b/packages/core/core-flows/src/order/steps/exchange/create-exchange-items-from-actions.ts index dfd8c26af9f0f..0682671eb8332 100644 --- a/packages/core/core-flows/src/order/steps/exchange/create-exchange-items-from-actions.ts +++ b/packages/core/core-flows/src/order/steps/exchange/create-exchange-items-from-actions.ts @@ -6,13 +6,40 @@ import { import { Modules } from "@medusajs/framework/utils" import { StepResponse, createStep } from "@medusajs/framework/workflows-sdk" +/** + * The details of creating exchange items from change actions. + */ export type CreateOrderExchangeItemsFromActionsInput = { + /** + * The change actions to create exchange items from. + */ changes: OrderChangeActionDTO[] + /** + * The ID of the exchange to create the items for. + */ exchangeId: string } /** * This step creates exchange items from change actions. + * + * :::note + * + * You can retrieve an order change action details using [Query](https://docs.medusajs.com/learn/fundamentals/module-links/query), + * or [useQueryGraphStep](https://docs.medusajs.com/resources/references/medusa-workflows/steps/useQueryGraphStep). + * + * ::: + * + * @example + * const data = createOrderExchangeItemsFromActionsStep({ + * exchangeId: "exchange_123", + * changes: [ + * { + * id: "orchact_123", + * // other order change action details... + * } + * ] + * }) */ export const createOrderExchangeItemsFromActionsStep = createStep( "create-exchange-items-from-change-actions", diff --git a/packages/core/core-flows/src/order/steps/exchange/delete-exchanges.ts b/packages/core/core-flows/src/order/steps/exchange/delete-exchanges.ts index 868491d95182d..bedb51718be93 100644 --- a/packages/core/core-flows/src/order/steps/exchange/delete-exchanges.ts +++ b/packages/core/core-flows/src/order/steps/exchange/delete-exchanges.ts @@ -2,13 +2,23 @@ import { IOrderModuleService } from "@medusajs/framework/types" import { Modules } from "@medusajs/framework/utils" import { createStep, StepResponse } from "@medusajs/framework/workflows-sdk" +/** + * The details of deleting one or more exchanges. + */ +export type DeleteOrderExchangesInput = { + /** + * The IDs of the exchanges to delete. + */ + ids: string[] +} + export const deleteExchangesStepId = "delete-exchanges" /** * This step deletes one or more exchanges. */ export const deleteExchangesStep = createStep( deleteExchangesStepId, - async (data: { ids: string[] }, { container }) => { + async (data: DeleteOrderExchangesInput, { container }) => { const service = container.resolve(Modules.ORDER) const deleted = await service.softDeleteOrderExchanges(data.ids) diff --git a/packages/core/core-flows/src/order/steps/exchange/update-order-exchanges.ts b/packages/core/core-flows/src/order/steps/exchange/update-order-exchanges.ts index 8d48d6f7dc0ad..61410ba8dc154 100644 --- a/packages/core/core-flows/src/order/steps/exchange/update-order-exchanges.ts +++ b/packages/core/core-flows/src/order/steps/exchange/update-order-exchanges.ts @@ -11,6 +11,12 @@ import { StepResponse, createStep } from "@medusajs/framework/workflows-sdk" export const updateOrderExchangesStepId = "update-order-exchange" /** * This step updates one or more exchanges. + * + * @example + * const data = updateOrderExchangesStep([{ + * "id": "exchange_123", + * no_notification: true + * }]) */ export const updateOrderExchangesStep = createStep( updateOrderExchangesStepId, diff --git a/packages/core/core-flows/src/order/steps/preview-order-change.ts b/packages/core/core-flows/src/order/steps/preview-order-change.ts index 2eb5bcede14c3..f587a6eeeeacb 100644 --- a/packages/core/core-flows/src/order/steps/preview-order-change.ts +++ b/packages/core/core-flows/src/order/steps/preview-order-change.ts @@ -2,13 +2,18 @@ import { IOrderModuleService } from "@medusajs/framework/types" import { Modules } from "@medusajs/framework/utils" import { StepResponse, createStep } from "@medusajs/framework/workflows-sdk" +/** + * The ID of the order to retrieve its preview. + */ +export type PreviewOrderChangeStepInput = string + export const previewOrderChangeStepId = "preview-order-change" /** * This step retrieves a preview of an order change. */ export const previewOrderChangeStep = createStep( previewOrderChangeStepId, - async (orderId: string, { container }) => { + async (orderId: PreviewOrderChangeStepInput, { container }) => { const service = container.resolve(Modules.ORDER) const preview = await service.previewOrderChange(orderId) diff --git a/packages/core/core-flows/src/order/steps/register-fulfillment.ts b/packages/core/core-flows/src/order/steps/register-fulfillment.ts index 82deeb644c0b1..aff7ed5223f60 100644 --- a/packages/core/core-flows/src/order/steps/register-fulfillment.ts +++ b/packages/core/core-flows/src/order/steps/register-fulfillment.ts @@ -8,6 +8,15 @@ import { StepResponse, createStep } from "@medusajs/framework/workflows-sdk" export const registerOrderFulfillmentStepId = "register-order-fullfillment" /** * This step registers a fulfillment for an order. + * + * @example + * const data = registerOrderFulfillmentStep({ + * order_id: "order_123", + * items: [{ + * id: "item_123", + * quantity: 1 + * }], + * }) */ export const registerOrderFulfillmentStep = createStep( registerOrderFulfillmentStepId, diff --git a/packages/core/core-flows/src/order/steps/register-order-changes.ts b/packages/core/core-flows/src/order/steps/register-order-changes.ts index dd5fb2f937c7e..76bbd2f3caac8 100644 --- a/packages/core/core-flows/src/order/steps/register-order-changes.ts +++ b/packages/core/core-flows/src/order/steps/register-order-changes.ts @@ -5,6 +5,11 @@ import { import { ModuleRegistrationName } from "@medusajs/framework/utils" import { StepResponse, createStep } from "@medusajs/framework/workflows-sdk" +/** + * The input of the register order changes step. + */ +export type RegisterOrderChangeStepInput = RegisterOrderChangeDTO[] + export const registerOrderChangeStepId = "register-order-change" /** @@ -12,7 +17,7 @@ export const registerOrderChangeStepId = "register-order-change" */ export const registerOrderChangesStep = createStep( registerOrderChangeStepId, - async (data: RegisterOrderChangeDTO[], { container }) => { + async (data: RegisterOrderChangeStepInput, { container }) => { const service = container.resolve( ModuleRegistrationName.ORDER ) diff --git a/packages/core/core-flows/src/order/steps/return/create-complete-return.ts b/packages/core/core-flows/src/order/steps/return/create-complete-return.ts index 485841aa3ccad..baddb993941c0 100644 --- a/packages/core/core-flows/src/order/steps/return/create-complete-return.ts +++ b/packages/core/core-flows/src/order/steps/return/create-complete-return.ts @@ -7,7 +7,7 @@ import { StepResponse, createStep } from "@medusajs/framework/workflows-sdk" export const createCompleteReturnStepId = "create-complete-return" /** - * This step creates a return. + * This step creates a complete return. */ export const createCompleteReturnStep = createStep( createCompleteReturnStepId, diff --git a/packages/core/core-flows/src/order/steps/return/delete-returns.ts b/packages/core/core-flows/src/order/steps/return/delete-returns.ts index ec31c7563c1a7..1a0b6ff548f82 100644 --- a/packages/core/core-flows/src/order/steps/return/delete-returns.ts +++ b/packages/core/core-flows/src/order/steps/return/delete-returns.ts @@ -2,13 +2,23 @@ import { IOrderModuleService } from "@medusajs/framework/types" import { Modules } from "@medusajs/framework/utils" import { createStep, StepResponse } from "@medusajs/framework/workflows-sdk" +/** + * The details of deleting the returns. + */ +export type DeleteReturnStepInput = { + /** + * The IDs of the returns to delete. + */ + ids: string[] +} + export const deleteReturnsStepId = "delete-return" /** * This step deletes one or more returns. */ export const deleteReturnsStep = createStep( deleteReturnsStepId, - async (data: { ids: string[] }, { container }) => { + async (data: DeleteReturnStepInput, { container }) => { const service = container.resolve(Modules.ORDER) const ids = data.ids.filter(Boolean) diff --git a/packages/core/core-flows/src/order/steps/return/update-return-items.ts b/packages/core/core-flows/src/order/steps/return/update-return-items.ts index 9b8d96553f1eb..53709d45004d5 100644 --- a/packages/core/core-flows/src/order/steps/return/update-return-items.ts +++ b/packages/core/core-flows/src/order/steps/return/update-return-items.ts @@ -4,18 +4,35 @@ import { } from "@medusajs/framework/utils" import { StepResponse, createStep } from "@medusajs/framework/workflows-sdk" -export interface UpdateReturnItemBySelector { +/** + * The details of updating the return items. + */ +export type UpdateReturnItemBySelector = { + /** + * The ID of the return item to update. + */ id: string + /** + * The data to update in the return item. + */ [key: string]: any -} +}[] export const updateReturnItemsStepId = "update-return-items" /** * This step updates return items. + * + * @example + * const data = updateReturnItemsStep([ + * { + * id: "orli_123", + * quantity: 2 + * } + * ]) */ export const updateReturnItemsStep = createStep( updateReturnItemsStepId, - async (data: UpdateReturnItemBySelector[], { container }) => { + async (data: UpdateReturnItemBySelector, { container }) => { const service = container.resolve(Modules.ORDER) as any const { selects, relations } = getSelectsAndRelationsFromObjectArray(data, { diff --git a/packages/core/core-flows/src/order/steps/return/update-returns.ts b/packages/core/core-flows/src/order/steps/return/update-returns.ts index b36f33ee9154c..d26eacd95d3c3 100644 --- a/packages/core/core-flows/src/order/steps/return/update-returns.ts +++ b/packages/core/core-flows/src/order/steps/return/update-returns.ts @@ -5,13 +5,18 @@ import { } from "@medusajs/framework/utils" import { StepResponse, createStep } from "@medusajs/framework/workflows-sdk" +/** + * The returns to update. + */ +export type UpdateReturnsStepInput = UpdateReturnDTO[] + export const updateReturnsStepId = "update-returns" /** * This step updates one or more returns. */ export const updateReturnsStep = createStep( updateReturnsStepId, - async (data: UpdateReturnDTO[], { container }) => { + async (data: UpdateReturnsStepInput, { container }) => { const service = container.resolve(Modules.ORDER) as any const { selects, relations } = getSelectsAndRelationsFromObjectArray(data, { diff --git a/packages/core/core-flows/src/order/steps/set-tax-lines-for-items.ts b/packages/core/core-flows/src/order/steps/set-tax-lines-for-items.ts index f1fdbef7a0187..1df39d822a8c0 100644 --- a/packages/core/core-flows/src/order/steps/set-tax-lines-for-items.ts +++ b/packages/core/core-flows/src/order/steps/set-tax-lines-for-items.ts @@ -9,15 +9,51 @@ import { import { Modules, promiseAll } from "@medusajs/framework/utils" import { StepResponse, createStep } from "@medusajs/framework/workflows-sdk" +/** + * The details of setting tax lines for an order's items and shipping methods. + */ export interface SetOrderTaxLinesForItemsStepInput { + /** + * The order's details. + */ order: OrderDTO + /** + * The tax lines to set for the order's items. + */ item_tax_lines: ItemTaxLineDTO[] + /** + * The tax lines to set for the order's shipping methods. + */ shipping_tax_lines: ShippingTaxLineDTO[] } export const setOrderTaxLinesForItemsStepId = "set-order-tax-lines-for-items" /** * This step sets the tax lines of an order's items and shipping methods. + * + * :::note + * + * You can retrieve an order's details using [Query](https://docs.medusajs.com/learn/fundamentals/module-links/query), + * or [useQueryGraphStep](https://docs.medusajs.com/resources/references/medusa-workflows/steps/useQueryGraphStep). + * + * ::: + * + * @example + * const data = setOrderTaxLinesForItemsStep({ + * order: { + * id: "order_123", + * // other order details... + * }, + * item_tax_lines: [ + * { + * line_item_id: "orli_123", + * rate: 0.25, + * code: "VAT", + * name: "VAT", + * provider_id: "tax_provider_123", + * } + * ] + * }) */ export const setOrderTaxLinesForItemsStep = createStep( setOrderTaxLinesForItemsStepId, diff --git a/packages/core/core-flows/src/order/steps/update-order-change-actions.ts b/packages/core/core-flows/src/order/steps/update-order-change-actions.ts index ebce48a4b2c5c..32b49192e4eed 100644 --- a/packages/core/core-flows/src/order/steps/update-order-change-actions.ts +++ b/packages/core/core-flows/src/order/steps/update-order-change-actions.ts @@ -9,13 +9,18 @@ import { } from "@medusajs/framework/utils" import { StepResponse, createStep } from "@medusajs/framework/workflows-sdk" +/** + * The order change actions to update. + */ +export type UpdateOrderChangeActionsStepInput = UpdateOrderChangeActionDTO[] + export const updateOrderChangeActionsStepId = "update-order-change-actions" /** * This step updates order change actions. */ export const updateOrderChangeActionsStep = createStep( updateOrderChangeActionsStepId, - async (data: UpdateOrderChangeActionDTO[], { container }) => { + async (data: UpdateOrderChangeActionsStepInput, { container }) => { const service = container.resolve(Modules.ORDER) const { selects, relations } = getSelectsAndRelationsFromObjectArray(data, { diff --git a/packages/core/core-flows/src/order/steps/update-order-changes.ts b/packages/core/core-flows/src/order/steps/update-order-changes.ts index 17c0e3ae122f1..d49e9be819286 100644 --- a/packages/core/core-flows/src/order/steps/update-order-changes.ts +++ b/packages/core/core-flows/src/order/steps/update-order-changes.ts @@ -8,13 +8,18 @@ import { } from "@medusajs/framework/utils" import { StepResponse, createStep } from "@medusajs/framework/workflows-sdk" +/** + * The order changes to update. + */ +export type UpdateOrderChangesStepInput = UpdateOrderChangeDTO[] + export const updateOrderChangesStepId = "update-order-shopping-methods" /** * This step updates order change. */ export const updateOrderChangesStep = createStep( updateOrderChangesStepId, - async (data: UpdateOrderChangeDTO[], { container }) => { + async (data: UpdateOrderChangesStepInput, { container }) => { const service = container.resolve(Modules.ORDER) const { selects, relations } = getSelectsAndRelationsFromObjectArray(data, { diff --git a/packages/core/core-flows/src/order/steps/update-order-exchanges.ts b/packages/core/core-flows/src/order/steps/update-order-exchanges.ts index 9887c327d327d..875717c5d522c 100644 --- a/packages/core/core-flows/src/order/steps/update-order-exchanges.ts +++ b/packages/core/core-flows/src/order/steps/update-order-exchanges.ts @@ -8,13 +8,18 @@ import { } from "@medusajs/framework/utils" import { StepResponse, createStep } from "@medusajs/framework/workflows-sdk" +/** + * The order exchanges to update. + */ +export type UpdateOrderExchangesStepInput = UpdateOrderExchangeDTO[] + export const updateOrderExchangesStepId = "update-order-exchange" /** * This step update order changes. */ export const updateOrderExchangesStep = createStep( updateOrderExchangesStepId, - async (data: UpdateOrderExchangeDTO[], { container }) => { + async (data: UpdateOrderExchangesStepInput, { container }) => { const service = container.resolve(Modules.ORDER) const { selects, relations } = getSelectsAndRelationsFromObjectArray(data, { diff --git a/packages/core/core-flows/src/order/steps/update-orders.ts b/packages/core/core-flows/src/order/steps/update-orders.ts index 1ffacaab2fb66..9412442aa7736 100644 --- a/packages/core/core-flows/src/order/steps/update-orders.ts +++ b/packages/core/core-flows/src/order/steps/update-orders.ts @@ -9,14 +9,33 @@ import { } from "@medusajs/framework/utils" import { StepResponse, createStep } from "@medusajs/framework/workflows-sdk" +/** + * The details of updating the orders. + */ export type UpdateOrdersStepInput = { + /** + * The filters to select the orders to update. + */ selector: FilterableOrderProps + /** + * The data to update in the orders. + */ update: UpdateOrderDTO // TODO: Update to UpdateOrderDTO[] } export const updateOrdersStepId = "update-orders" /** * This step updates orders matching the specified filters. + * + * @example + * const data = updateOrdersStep({ + * selector: { + * id: "order_123" + * }, + * update: { + * region_id: "region_123" + * } + * }) */ export const updateOrdersStep = createStep( updateOrdersStepId, diff --git a/packages/core/core-flows/src/order/steps/update-shipping-methods.ts b/packages/core/core-flows/src/order/steps/update-shipping-methods.ts index 7a07ab4114b2d..3f3c0b5fb7af8 100644 --- a/packages/core/core-flows/src/order/steps/update-shipping-methods.ts +++ b/packages/core/core-flows/src/order/steps/update-shipping-methods.ts @@ -8,13 +8,18 @@ import { } from "@medusajs/framework/utils" import { StepResponse, createStep } from "@medusajs/framework/workflows-sdk" +/** + * The order shipping methods to update. + */ +export type UpdateOrderShippingMethodsStepInput = UpdateOrderShippingMethodDTO[] + export const updateOrderShippingMethodsStepId = "update-order-shopping-methods" /** * This step updates order shipping methods. */ export const updateOrderShippingMethodsStep = createStep( updateOrderShippingMethodsStepId, - async (data: UpdateOrderShippingMethodDTO[], { container }) => { + async (data: UpdateOrderShippingMethodsStepInput, { container }) => { const service = container.resolve(Modules.ORDER) const { selects, relations } = getSelectsAndRelationsFromObjectArray(data, { diff --git a/packages/core/core-flows/src/order/workflows/add-line-items.ts b/packages/core/core-flows/src/order/workflows/add-line-items.ts index 3ac6d2f0df3de..b3ad4ca971f91 100644 --- a/packages/core/core-flows/src/order/workflows/add-line-items.ts +++ b/packages/core/core-flows/src/order/workflows/add-line-items.ts @@ -48,15 +48,42 @@ function prepareLineItems(data) { return items } +/** + * The created order line items. + */ +export type OrderAddLineItemWorkflowOutput = OrderLineItemDTO[] + export const addOrderLineItemsWorkflowId = "order-add-line-items" /** - * This workflow adds line items to an order. + * This workflow adds line items to an order. This is useful when making edits to + * an order. It's used by other workflows, such as {@link orderEditAddNewItemWorkflow}. + * + * You can use this workflow within your customizations or your own custom workflows, allowing you to wrap custom logic around adding items to + * an order. + * + * @example + * const { result } = await addOrderLineItemsWorkflow(container) + * .run({ + * input: { + * order_id: "order_123", + * items: [ + * { + * variant_id: "variant_123", + * quantity: 1, + * } + * ] + * } + * }) + * + * @summary + * + * Add line items to an order. */ export const addOrderLineItemsWorkflow = createWorkflow( addOrderLineItemsWorkflowId, ( input: WorkflowData - ): WorkflowResponse => { + ): WorkflowResponse => { const order = useRemoteQueryStep({ entry_point: "orders", fields: [ diff --git a/packages/core/core-flows/src/order/workflows/archive-orders.ts b/packages/core/core-flows/src/order/workflows/archive-orders.ts index bb3ecf6c320f2..19e578ff69ef3 100644 --- a/packages/core/core-flows/src/order/workflows/archive-orders.ts +++ b/packages/core/core-flows/src/order/workflows/archive-orders.ts @@ -9,19 +9,45 @@ import { import { emitEventStep } from "../../common/steps/emit-event" import { archiveOrdersStep } from "../steps" +/** + * The details of the orders to archive. + */ export type ArchiveOrdersWorkflowInput = { + /** + * The IDs of the orders to archive. + */ orderIds: string[] } +/** + * The archived orders. + */ +export type ArchiveOrdersWorkflowOutput = OrderDTO[] + export const archiveOrderWorkflowId = "archive-order-workflow" /** - * This workflow archives an order. + * This workflow archives one or more orders. It's used by the + * [Archive Order Admin API Route](https://docs.medusajs.com/api/admin#orders_postordersidarchive). + * + * You can use this workflow within your customizations or your own custom workflows, allowing you to wrap custom logic around archiving orders. + * + * @example + * const { result } = await archiveOrderWorkflow(container) + * .run({ + * input: { + * orderIds: ["order_123"] + * } + * }) + * + * @summary + * + * Archive one or more orders. */ export const archiveOrderWorkflow = createWorkflow( archiveOrderWorkflowId, ( input: WorkflowData - ): WorkflowResponse => { + ): WorkflowResponse => { const eventData = transform({ input }, (data) => { return data.input.orderIds.map((id) => ({ id })) }) diff --git a/packages/core/core-flows/src/order/workflows/cancel-order-change.ts b/packages/core/core-flows/src/order/workflows/cancel-order-change.ts index f31cd6db1dd73..2524932d2b9d7 100644 --- a/packages/core/core-flows/src/order/workflows/cancel-order-change.ts +++ b/packages/core/core-flows/src/order/workflows/cancel-order-change.ts @@ -5,6 +5,13 @@ import { cancelOrderChangeStep } from "../steps" export const cancelOrderChangeWorkflowId = "cancel-order-change" /** * This workflow cancels an order change. + * + * You can use this workflow within your customizations or your own custom workflows, allowing you to wrap custom logic around + * canceling an order change. + * + * @summary + * + * Cancel an order change. */ export const cancelOrderChangeWorkflow = createWorkflow( cancelOrderChangeWorkflowId, diff --git a/packages/core/core-flows/src/order/workflows/cancel-order-fulfillment.ts b/packages/core/core-flows/src/order/workflows/cancel-order-fulfillment.ts index 9a62d173c6f46..c4231489532e4 100644 --- a/packages/core/core-flows/src/order/workflows/cancel-order-fulfillment.ts +++ b/packages/core/core-flows/src/order/workflows/cancel-order-fulfillment.ts @@ -29,17 +29,59 @@ import { } from "../utils/order-validation" /** - * This step validates that an order fulfillment can be canceled. + * The data to validate the order fulfillment cancelation. + */ +export type CancelOrderFulfillmentValidateOrderStep = { + /** + * The order to cancel the fulfillment for. + */ + order: OrderDTO & { + /** + * The order's fulfillments. + */ + fulfillments: FulfillmentDTO[] + } + /** + * The cancelation details. + */ + input: OrderWorkflow.CancelOrderFulfillmentWorkflowInput +} + +/** + * This step validates that an order fulfillment can be canceled. If + * the fulfillment doesn't exist, or it has already been shipped, the step throws an error. + * + * :::note + * + * You can retrieve an order and fulfillment details using [Query](https://docs.medusajs.com/learn/fundamentals/module-links/query), + * or [useQueryGraphStep](https://docs.medusajs.com/resources/references/medusa-workflows/steps/useQueryGraphStep). + * + * ::: + * + * @example + * const data = cancelOrderFulfillmentValidateOrder({ + * order: { + * id: "order_123", + * fulfillments: [ + * { + * id: "ful_123", + * // other fulfillment details... + * } + * ] + * // other order details... + * }, + * input: { + * order_id: "order_123", + * fulfillment_id: "ful_123" + * } + * }) */ export const cancelOrderFulfillmentValidateOrder = createStep( "cancel-fulfillment-validate-order", ({ order, input, - }: { - order: OrderDTO & { fulfillments: FulfillmentDTO[] } - input: OrderWorkflow.CancelOrderFulfillmentWorkflowInput - }) => { + }: CancelOrderFulfillmentValidateOrderStep) => { throwIfOrderIsCancelled({ order }) const fulfillment = order.fulfillments.find( @@ -127,7 +169,7 @@ export const cancelOrderFulfillmentWorkflowId = "cancel-order-fulfillment" * 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. + * You can also use this workflow within your customizations or your own custom workflows, allowing you to wrap custom logic around canceling a fulfillment. * * @example * const { result } = await cancelOrderFulfillmentWorkflow(container) diff --git a/packages/core/core-flows/src/order/workflows/cancel-order.ts b/packages/core/core-flows/src/order/workflows/cancel-order.ts index 72c24ff105b20..ea3a9c8e39636 100644 --- a/packages/core/core-flows/src/order/workflows/cancel-order.ts +++ b/packages/core/core-flows/src/order/workflows/cancel-order.ts @@ -31,16 +31,46 @@ import { createOrderRefundCreditLinesWorkflow } from "./payments/create-order-re import { refundCapturedPaymentsWorkflow } from "./payments/refund-captured-payments" /** - * This step validates that an order can be canceled. + * The data to validate the order's cancelation. + */ +export type CancelValidateOrderStepInput = { + /** + * The order to cancel. + */ + order: OrderDTO + /** + * The cancelation details. + */ + input: OrderWorkflow.CancelOrderWorkflowInput +} + +/** + * This step validates that an order can be canceled. If the order has fulfillments that + * aren't canceled, or the order was canceled previously, the step throws an error. + * + * :::note + * + * You can retrieve an order's details using [Query](https://docs.medusajs.com/learn/fundamentals/module-links/query), + * or [useQueryGraphStep](https://docs.medusajs.com/resources/references/medusa-workflows/steps/useQueryGraphStep). + * + * ::: + * + * @example + * const data = cancelValidateOrder({ + * order: { + * id: "order_123", + * // other order details... + * }, + * input: { + * order_id: "order_123", + * } + * }) */ export const cancelValidateOrder = createStep( "cancel-validate-order", ({ order, - }: { - order: OrderDTO - input: OrderWorkflow.CancelOrderWorkflowInput - }) => { + }: CancelValidateOrderStepInput) => { const order_ = order as OrderDTO & { payment_collections: PaymentCollectionDTO[] fulfillments: FulfillmentDTO[] @@ -69,7 +99,30 @@ export const cancelValidateOrder = createStep( export const cancelOrderWorkflowId = "cancel-order" /** - * This workflow cancels an order. + * This workflow cancels an order. An order can only be canceled if it doesn't have + * any fulfillments, or if all fulfillments are canceled. The workflow will also cancel + * any uncaptured payments, and refund any captured payments. + * + * This workflow is used by the [Cancel Order Admin API Route](https://docs.medusajs.com/api/admin#orders_postordersidcancel). + * + * This workflow has a hook that allows you to perform custom actions on the canceled order. For example, you can + * make changes to custom models linked to the order. + * + * You can also use this workflow within your customizations or your own custom workflows, allowing you to wrap custom logic around canceling an order. + * + * @example + * const { result } = await cancelOrderWorkflow(container) + * .run({ + * input: { + * order_id: "order_123", + * } + * }) + * + * @summary + * + * Cancel an order. + * + * @property hooks.orderCanceled - This hook is executed after the order is canceled. You can consume this hook to perform custom actions on the canceled order. */ export const cancelOrderWorkflow = createWorkflow( cancelOrderWorkflowId, diff --git a/packages/core/core-flows/src/order/workflows/claim/begin-order-claim.ts b/packages/core/core-flows/src/order/workflows/claim/begin-order-claim.ts index ba43b77489438..c5e14e88c624c 100644 --- a/packages/core/core-flows/src/order/workflows/claim/begin-order-claim.ts +++ b/packages/core/core-flows/src/order/workflows/claim/begin-order-claim.ts @@ -15,19 +15,62 @@ import { createOrderClaimsStep } from "../../steps/claim/create-claims" import { createOrderChangeStep } from "../../steps/create-order-change" import { throwIfIsCancelled } from "../../utils/order-validation" +/** + * The data to validate that an order can have a claim + */ +export type BeginClaimOrderValidationStepInput = { + /** + * The order's details. + */ + order: OrderDTO +} + /** * This step validates that the order associated with the claim isn't canceled. + * If not valid, the step will throw an error. + * + * :::note + * + * You can retrieve an order's details using [Query](https://docs.medusajs.com/learn/fundamentals/module-links/query), + * or [useQueryGraphStep](https://docs.medusajs.com/resources/references/medusa-workflows/steps/useQueryGraphStep). + * + * ::: + * + * @example + * const data = beginClaimOrderValidationStep({ + * order: { + * id: "order_123", + * // other order details... + * }, + * }) */ export const beginClaimOrderValidationStep = createStep( "begin-claim-order-validation", - async function ({ order }: { order: OrderDTO }) { + async function ({ order }: BeginClaimOrderValidationStepInput) { throwIfIsCancelled(order, "Order") } ) export const beginClaimOrderWorkflowId = "begin-claim-order" /** - * This workflow creates an order claim in requested state. + * This workflow creates an order claim in requested state. It's used by the + * [Create Claim Admin API Route](https://docs.medusajs.com/api/admin#claims_postclaims). + * + * You can use this workflow within your customizations or your own custom workflows, allowing you to create a claim + * for an order in your custom flows. + * + * @example + * const { result } = await beginClaimOrderWorkflow(container) + * .run({ + * input: { + * order_id: "order_123", + * type: "refund", + * } + * }) + * + * @summary + * + * Create an order claim in requested state. */ export const beginClaimOrderWorkflow = createWorkflow( beginClaimOrderWorkflowId, diff --git a/packages/core/core-flows/src/order/workflows/claim/cancel-begin-order-claim.ts b/packages/core/core-flows/src/order/workflows/claim/cancel-begin-order-claim.ts index 0f1f106df2087..1e405d3343637 100644 --- a/packages/core/core-flows/src/order/workflows/claim/cancel-begin-order-claim.ts +++ b/packages/core/core-flows/src/order/workflows/claim/cancel-begin-order-claim.ts @@ -23,13 +23,50 @@ import { throwIfOrderChangeIsNotActive, } from "../../utils/order-validation" -export type CancelBeginOrderClaimWorkflowInput = { - claim_id: string +/** + * The data to validate the cancelation of a requested order claim. + */ +export type CancelBeginOrderClaimValidationStepInput = { + /** + * The order's details. + */ + order: OrderDTO + /** + * The order claim's details. + */ + orderClaim: OrderClaimDTO + /** + * The order change's details. + */ + orderChange: OrderChangeDTO } /** * This step validates that the requested claim can be canceled by checking that it's not canceled, - * its order isn't canceled, and it hasn't been confirmed. + * its order isn't canceled, and it hasn't been confirmed. If not valid, the step will throw an error. + * + * :::note + * + * You can retrieve an order, order claim, and order change details using [Query](https://docs.medusajs.com/learn/fundamentals/module-links/query), + * or [useQueryGraphStep](https://docs.medusajs.com/resources/references/medusa-workflows/steps/useQueryGraphStep). + * + * ::: + * + * @example + * const data = cancelBeginOrderClaimValidationStep({ + * order: { + * id: "order_123", + * // other order details... + * }, + * orderChange: { + * id: "orch_123", + * // other order change details... + * }, + * orderClaim: { + * id: "claim_123", + * // other order claim details... + * } + * }) */ export const cancelBeginOrderClaimValidationStep = createStep( "validate-cancel-begin-order-claim", @@ -37,20 +74,42 @@ export const cancelBeginOrderClaimValidationStep = createStep( order, orderChange, orderClaim, - }: { - order: OrderDTO - orderClaim: OrderClaimDTO - orderChange: OrderChangeDTO - }) { + }: CancelBeginOrderClaimValidationStepInput) { throwIfIsCancelled(order, "Order") throwIfIsCancelled(orderClaim, "Claim") throwIfOrderChangeIsNotActive({ orderChange }) } ) +/** + * The data to cancel a requested order claim. + */ +export type CancelBeginOrderClaimWorkflowInput = { + /** + * The ID of the claim to cancel. + */ + claim_id: string +} + export const cancelBeginOrderClaimWorkflowId = "cancel-begin-order-claim" /** - * This workflow cancels a requested order claim. + * This workflow cancels a requested order claim. It's used by the + * [Cancel Claim Request Admin API Route](https://docs.medusajs.com/api/admin#claims_deleteclaimsidrequest). + * + * You can use this workflow within your customizations or your own custom workflows, allowing you to cancel a claim + * for an order in your custom flows. + * + * @example + * const { result } = await cancelBeginOrderClaimWorkflow(container) + * .run({ + * input: { + * claim_id: "claim_123", + * } + * }) + * + * @summary + * + * Cancel a requested order claim. */ export const cancelBeginOrderClaimWorkflow = createWorkflow( cancelBeginOrderClaimWorkflowId, diff --git a/packages/core/core-flows/src/order/workflows/claim/cancel-claim.ts b/packages/core/core-flows/src/order/workflows/claim/cancel-claim.ts index 0a60537f69d0b..50c772bb2736d 100644 --- a/packages/core/core-flows/src/order/workflows/claim/cancel-claim.ts +++ b/packages/core/core-flows/src/order/workflows/claim/cancel-claim.ts @@ -19,16 +19,46 @@ import { throwIfIsCancelled } from "../../utils/order-validation" import { cancelReturnWorkflow } from "../return/cancel-return" /** - * This step validates that a confirmed claim can be canceled. + * The data to validate the cancelation of a confirmed order claim. + */ +export type CancelClaimValidateOrderStepInput = { + /** + * The order claim's details. + */ + orderClaim: OrderClaimDTO + /** + * The cancelation details. + */ + input: OrderWorkflow.CancelOrderClaimWorkflowInput +} + +/** + * This step validates that a confirmed claim can be canceled. If the claim is canceled, + * or the claim's fulfillments are not canceled, the step will throw an error. + * + * :::note + * + * You can retrieve an order claim's details using [Query](https://docs.medusajs.com/learn/fundamentals/module-links/query), + * or [useQueryGraphStep](https://docs.medusajs.com/resources/references/medusa-workflows/steps/useQueryGraphStep). + * + * ::: + * + * @example + * const data = cancelClaimValidateOrderStep({ + * orderClaim: { + * id: "claim_123", + * // other order claim details... + * }, + * input: { + * claim_id: "claim_123", + * } + * }) */ export const cancelClaimValidateOrderStep = createStep( "validate-claim", ({ orderClaim, - }: { - orderClaim: OrderClaimDTO - input: OrderWorkflow.CancelOrderClaimWorkflowInput - }) => { + }: CancelClaimValidateOrderStepInput) => { const orderClaim_ = orderClaim as OrderClaimDTO & { fulfillments: FulfillmentDTO[] } @@ -57,7 +87,23 @@ export const cancelClaimValidateOrderStep = createStep( export const cancelOrderClaimWorkflowId = "cancel-claim" /** - * This workflow cancels a confirmed order claim. + * This workflow cancels a confirmed order claim. It's used by the + * [Cancel Claim API Route](https://docs.medusajs.com/api/admin#claims_postclaimsidcancel). + * + * You can use this workflow within your customizations or your own custom workflows, allowing you to cancel a claim + * for an order in your custom flows. + * + * @example + * const { result } = await cancelOrderClaimWorkflow(container) + * .run({ + * input: { + * claim_id: "claim_123", + * } + * }) + * + * @summary + * + * Cancel a confirmed order claim. */ export const cancelOrderClaimWorkflow = createWorkflow( cancelOrderClaimWorkflowId, diff --git a/packages/core/core-flows/src/order/workflows/claim/claim-add-new-item.ts b/packages/core/core-flows/src/order/workflows/claim/claim-add-new-item.ts index d228ab963a95b..d46d36661210a 100644 --- a/packages/core/core-flows/src/order/workflows/claim/claim-add-new-item.ts +++ b/packages/core/core-flows/src/order/workflows/claim/claim-add-new-item.ts @@ -24,7 +24,49 @@ import { createOrderChangeActionsWorkflow } from "../create-order-change-actions import { updateOrderTaxLinesWorkflow } from "../update-tax-lines" /** - * This step validates that a new item can be added to the claim. + * The data to validate adding new items to a claim. + */ +export type OrderClaimAddNewItemValidationStepInput = { + /** + * The order's details. + */ + order: OrderDTO + /** + * The order claim's details. + */ + orderClaim: OrderClaimDTO + /** + * The order change's details. + */ + orderChange: OrderChangeDTO +} + +/** + * This step validates that new items can be added to the claim. If the + * order or claim is canceled, or the order change is not active, the step will throw an error. + * + * :::note + * + * You can retrieve an order, order claim, and order change details using [Query](https://docs.medusajs.com/learn/fundamentals/module-links/query), + * or [useQueryGraphStep](https://docs.medusajs.com/resources/references/medusa-workflows/steps/useQueryGraphStep). + * + * ::: + * + * @example + * const data = orderClaimAddNewItemValidationStep({ + * order: { + * id: "order_123", + * // other order details... + * }, + * orderChange: { + * id: "orch_123", + * // other order change details... + * }, + * orderClaim: { + * id: "claim_123", + * // other order claim details... + * } + * }) */ export const orderClaimAddNewItemValidationStep = createStep( "claim-add-new-item-validation", @@ -32,11 +74,7 @@ export const orderClaimAddNewItemValidationStep = createStep( order, orderChange, orderClaim, - }: { - order: OrderDTO - orderClaim: OrderClaimDTO - orderChange: OrderChangeDTO - }) { + }: OrderClaimAddNewItemValidationStepInput) { throwIfIsCancelled(order, "Order") throwIfIsCancelled(orderClaim, "Claim") throwIfOrderChangeIsNotActive({ orderChange }) @@ -45,7 +83,29 @@ export const orderClaimAddNewItemValidationStep = createStep( export const orderClaimAddNewItemWorkflowId = "claim-add-new-item" /** - * This workflow adds a new item to a claim. + * This workflow adds outbound (or new) items to a claim. It's used by the + * [Add Outbound Items Admin API Route](https://docs.medusajs.com/api/admin#claims_postclaimsidoutbounditems). + * + * You can use this workflow within your customizations or your own custom workflows, allowing you to add outbound items to a claim + * in your custom flows. + * + * @example + * const { result } = await orderClaimAddNewItemWorkflow(container) + * .run({ + * input: { + * claim_id: "claim_123", + * items: [ + * { + * variant_id: "variant_123", + * quantity: 1 + * } + * ] + * } + * }) + * + * @summary + * + * Add outbound or new items to a claim. */ export const orderClaimAddNewItemWorkflow = createWorkflow( orderClaimAddNewItemWorkflowId, diff --git a/packages/core/core-flows/src/order/workflows/claim/claim-item.ts b/packages/core/core-flows/src/order/workflows/claim/claim-item.ts index 4e9ccaca9ccd1..d97b70cf0bf07 100644 --- a/packages/core/core-flows/src/order/workflows/claim/claim-item.ts +++ b/packages/core/core-flows/src/order/workflows/claim/claim-item.ts @@ -22,7 +22,49 @@ import { import { createOrderChangeActionsWorkflow } from "../create-order-change-actions" /** - * This step validates that claim items can be added to a claim. + * The data to validate that claim items can be added to a claim. + */ +export type OrderClaimItemValidationStepInput = { + /** + * The order's details. + */ + order: OrderDTO + /** + * The order claim's details. + */ + orderClaim: OrderClaimDTO + /** + * The order change's details. + */ + orderChange: OrderChangeDTO +} + +/** + * This step validates that claim items can be added to a claim. If the + * order or claim is canceled, or the order change is not active, the step will throw an error. + * + * :::note + * + * You can retrieve an order, order claim, and order change details using [Query](https://docs.medusajs.com/learn/fundamentals/module-links/query), + * or [useQueryGraphStep](https://docs.medusajs.com/resources/references/medusa-workflows/steps/useQueryGraphStep). + * + * ::: + * + * @example + * const data = orderClaimItemValidationStep({ + * order: { + * id: "order_123", + * // other order details... + * }, + * orderChange: { + * id: "orch_123", + * // other order change details... + * }, + * orderClaim: { + * id: "claim_123", + * // other order claim details... + * } + * }) */ export const orderClaimItemValidationStep = createStep( "claim-item-validation", @@ -43,7 +85,29 @@ export const orderClaimItemValidationStep = createStep( export const orderClaimItemWorkflowId = "claim-item" /** - * This workflow adds claim items to a claim. + * This workflow adds order items to a claim as claim items. It's used by the + * [Add Claim Items Admin API Route](https://docs.medusajs.com/api/admin#claims_postclaimsidclaimitems). + * + * You can use this workflow within your customizations or your own custom workflows, allowing you to add items to a claim + * for an order in your custom flows. + * + * @example + * const { result } = await orderClaimItemWorkflow(container) + * .run({ + * input: { + * claim_id: "claim_123", + * items: [ + * { + * id: "orli_123", + * quantity: 1 + * } + * ] + * } + * }) + * + * @summary + * + * Add order items to a claim as claim items. */ export const orderClaimItemWorkflow = createWorkflow( orderClaimItemWorkflowId, diff --git a/packages/core/core-flows/src/order/workflows/claim/claim-request-item-return.ts b/packages/core/core-flows/src/order/workflows/claim/claim-request-item-return.ts index 7a63914a3b6b1..d972c2f9d90fd 100644 --- a/packages/core/core-flows/src/order/workflows/claim/claim-request-item-return.ts +++ b/packages/core/core-flows/src/order/workflows/claim/claim-request-item-return.ts @@ -27,8 +27,68 @@ import { } from "../../utils/order-validation" import { createOrderChangeActionsWorkflow } from "../create-order-change-actions" +/** + * The data to validate that items can be requested to return as part of a claim. + */ +export type OrderClaimRequestItemReturnValidationStepInput = { + /** + * The order's details. + */ + order: OrderDTO + /** + * The order return's details. + */ + orderReturn: ReturnDTO + /** + * The order claim's details. + */ + orderClaim: OrderClaimDTO + /** + * The order change's details. + */ + orderChange: OrderChangeDTO + /** + * The items requested to return. + */ + items: OrderWorkflow.OrderClaimRequestItemReturnWorkflowInput["items"] +} + /** * This step validates that items can be requested to return as part of a claim. + * If the order, claim, or return is canceled, or the order change is not active, the step will throw an error. + * + * :::note + * + * You can retrieve an order, order claim, order return, and order change details using [Query](https://docs.medusajs.com/learn/fundamentals/module-links/query), + * or [useQueryGraphStep](https://docs.medusajs.com/resources/references/medusa-workflows/steps/useQueryGraphStep). + * + * ::: + * + * @example + * const data = orderClaimRequestItemReturnValidationStep({ + * order: { + * id: "order_123", + * // other order details... + * }, + * orderChange: { + * id: "orch_123", + * // other order change details... + * }, + * orderClaim: { + * id: "claim_123", + * // other order claim details... + * }, + * orderReturn: { + * id: "return_123", + * // other order return details... + * }, + * items: [ + * { + * id: "orli_123", + * quantity: 1 + * } + * ] + * }) */ export const orderClaimRequestItemReturnValidationStep = createStep( "claim-request-item-return-validation", @@ -38,13 +98,7 @@ export const orderClaimRequestItemReturnValidationStep = createStep( orderReturn, orderClaim, items, - }: { - order: OrderDTO - orderReturn: ReturnDTO - orderClaim: OrderClaimDTO - orderChange: OrderChangeDTO - items: OrderWorkflow.OrderClaimRequestItemReturnWorkflowInput["items"] - }) { + }: OrderClaimRequestItemReturnValidationStepInput) { throwIfIsCancelled(order, "Order") throwIfIsCancelled(orderClaim, "Claim") throwIfIsCancelled(orderReturn, "Return") @@ -55,7 +109,31 @@ export const orderClaimRequestItemReturnValidationStep = createStep( export const orderClaimRequestItemReturnWorkflowId = "claim-request-item-return" /** - * This workflow requests one or more items to be returned as part of a claim. + * This workflow requests one or more items to be returned as part of a claim. The + * items are added to the claim as inbound items. The workflow is used by the + * [Add Inbound Items to Claim Admin API Route](https://docs.medusajs.com/api/admin#claims_postclaimsidinbounditems). + * + * You can use this workflow within your customizations or your own custom workflows, allowing you to request items to be returned + * as part of a claim in your custom flows. + * + * @example + * const { result } = await orderClaimRequestItemReturnWorkflow(container) + * .run({ + * input: { + * claim_id: "claim_123", + * return_id: "return_123", + * items: [ + * { + * id: "orli_123", + * quantity: 1 + * } + * ] + * } + * }) + * + * @summary + * + * Request one or more items to be returned as part of a claim. */ export const orderClaimRequestItemReturnWorkflow = createWorkflow( orderClaimRequestItemReturnWorkflowId, diff --git a/packages/core/core-flows/src/order/workflows/claim/confirm-claim-request.ts b/packages/core/core-flows/src/order/workflows/claim/confirm-claim-request.ts index 6f8a2999780e6..b8137eba59f1a 100644 --- a/packages/core/core-flows/src/order/workflows/claim/confirm-claim-request.ts +++ b/packages/core/core-flows/src/order/workflows/claim/confirm-claim-request.ts @@ -42,11 +42,6 @@ import { } from "../../utils/order-validation" import { createOrUpdateOrderPaymentCollectionWorkflow } from "../create-or-update-order-payment-collection" -export type ConfirmClaimRequestWorkflowInput = { - claim_id: string - confirmed_by?: string -} - function getUpdateReturnData({ returnId }: { returnId: string }) { return transform({ returnId }, ({ returnId }) => { return [ @@ -60,7 +55,49 @@ function getUpdateReturnData({ returnId }: { returnId: string }) { } /** - * This step validates that a requested claim can be confirmed. + * The data to validate confirming a claim request. + */ +export type ConfirmClaimRequestValidationStepInput = { + /** + * The order's details. + */ + order: OrderDTO + /** + * The order claim's details. + */ + orderClaim: OrderClaimDTO + /** + * The order change's details. + */ + orderChange: OrderChangeDTO +} + +/** + * This step validates that a requested claim can be confirmed. If the order or claim is canceled, + * or the order change is not active, the step will throw an error. + * + * :::note + * + * You can retrieve an order, order claim, and order change details using [Query](https://docs.medusajs.com/learn/fundamentals/module-links/query), + * or [useQueryGraphStep](https://docs.medusajs.com/resources/references/medusa-workflows/steps/useQueryGraphStep). + * + * ::: + * + * @example + * const data = confirmClaimRequestValidationStep({ + * order: { + * id: "order_123", + * // other order details... + * }, + * orderChange: { + * id: "orch_123", + * // other order change details... + * }, + * orderClaim: { + * id: "claim_123", + * // other order claim details... + * }, + * }) */ export const confirmClaimRequestValidationStep = createStep( "validate-confirm-claim-request", @@ -68,11 +105,7 @@ export const confirmClaimRequestValidationStep = createStep( order, orderChange, orderClaim, - }: { - order: OrderDTO - orderClaim: OrderClaimDTO - orderChange: OrderChangeDTO - }) { + }: ConfirmClaimRequestValidationStepInput) { throwIfIsCancelled(order, "Order") throwIfIsCancelled(orderClaim, "Claim") throwIfOrderChangeIsNotActive({ orderChange }) @@ -221,9 +254,39 @@ function extractShippingOption({ orderPreview, orderClaim, returnId }) { } } +/** + * The details of confirming the claim request. + */ +export type ConfirmClaimRequestWorkflowInput = { + /** + * The ID of the claim to confirm. + */ + claim_id: string + /** + * The ID of the user confirming the claim. + */ + confirmed_by?: string +} + export const confirmClaimRequestWorkflowId = "confirm-claim-request" /** - * This workflow confirms a requested claim. + * This workflow confirms a requested claim. It's used by the + * [Confirm Claim Request API Route](https://docs.medusajs.com/api/admin#claims_postclaimsidrequest). + * + * You can use this workflow within your customizations or your own custom workflows, allowing you to confirm a claim + * for an order in your custom flows. + * + * @example + * const { result } = await confirmClaimRequestWorkflow(container) + * .run({ + * input: { + * claim_id: "claim_123", + * } + * }) + * + * @summary + * + * Confirm a requested claim. */ export const confirmClaimRequestWorkflow = createWorkflow( confirmClaimRequestWorkflowId, diff --git a/packages/core/core-flows/src/order/workflows/claim/create-claim-shipping-method.ts b/packages/core/core-flows/src/order/workflows/claim/create-claim-shipping-method.ts index 2ee1a990b5c5d..eaf268332528a 100644 --- a/packages/core/core-flows/src/order/workflows/claim/create-claim-shipping-method.ts +++ b/packages/core/core-flows/src/order/workflows/claim/create-claim-shipping-method.ts @@ -23,8 +23,50 @@ import { prepareShippingMethod } from "../../utils/prepare-shipping-method" import { createOrderChangeActionsWorkflow } from "../create-order-change-actions" import { updateOrderTaxLinesWorkflow } from "../update-tax-lines" +/** + * The data to validate that a shipping method can be created for a claim. + */ +export type CreateClaimShippingMethodValidationStepInput = { + /** + * The order's details. + */ + order: OrderDTO + /** + * The order claim's details. + */ + orderClaim: OrderClaimDTO + /** + * The order change's details. + */ + orderChange: OrderChangeDTO +} + /** * This step confirms that a shipping method can be created for a claim. + * If the order or claim is canceled, or the order change is not active, the step will throw an error. + * + * :::note + * + * You can retrieve an order, order claim, and order change details using [Query](https://docs.medusajs.com/learn/fundamentals/module-links/query), + * or [useQueryGraphStep](https://docs.medusajs.com/resources/references/medusa-workflows/steps/useQueryGraphStep). + * + * ::: + * + * @example + * const data = createClaimShippingMethodValidationStep({ + * order: { + * id: "order_123", + * // other order details... + * }, + * orderChange: { + * id: "orch_123", + * // other order change details... + * }, + * orderClaim: { + * id: "claim_123", + * // other order claim details... + * }, + * }) */ export const createClaimShippingMethodValidationStep = createStep( "validate-create-claim-shipping-method", @@ -32,30 +74,80 @@ export const createClaimShippingMethodValidationStep = createStep( order, orderChange, orderClaim, - }: { - order: OrderDTO - orderClaim: OrderClaimDTO - orderChange: OrderChangeDTO - }) { + }: CreateClaimShippingMethodValidationStepInput) { throwIfIsCancelled(order, "Order") throwIfIsCancelled(orderClaim, "Claim") throwIfOrderChangeIsNotActive({ orderChange }) } ) +/** + * The data to create a shipping method for a claim. + */ +export type CreateClaimShippingMethodWorkflowInput = { + /** + * The ID of the return associated with the claim. + * If this is set, the shipping method will be created as an inbound (return) shipping method. + * If not set, the shipping method will be created as an outbound (delivering new items) shipping method. + */ + return_id?: string + /** + * The ID of the claim to create the shipping method for. + */ + claim_id?: string + /** + * The ID of the shipping option to create the shipping method from. + */ + shipping_option_id: string + /** + * A custom amount to set for the shipping method. If not set, the shipping option's amount is used. + */ + custom_amount?: BigNumberInput | null +} + export const createClaimShippingMethodWorkflowId = "create-claim-shipping-method" /** - * This workflow creates a shipping method for a claim. + * This workflow creates an inbound (return) or outbound (delivering new items) shipping method for a claim. + * It's used by the [Add Inbound Shipping Admin API Route](https://docs.medusajs.com/api/admin#claims_postclaimsidinboundshippingmethod), + * and the [Add Outbound Shipping Admin API Route](https://docs.medusajs.com/api/admin#claims_postclaimsidoutboundshippingmethod). + * + * You can use this workflow within your customizations or your own custom workflows, allowing you to create a shipping method + * for a claim in your custom flows. + * + * @example + * To create an outbound shipping method for a claim: + * + * ```ts + * const { result } = await createClaimShippingMethodWorkflow(container) + * .run({ + * input: { + * claim_id: "claim_123", + * shipping_option_id: "so_123", + * } + * }) + * ``` + * + * To create an inbound shipping method for a claim, specify the ID of the return associated with the claim: + * + * ```ts + * const { result } = await createClaimShippingMethodWorkflow(container) + * .run({ + * input: { + * claim_id: "claim_123", + * return_id: "return_123", + * shipping_option_id: "so_123", + * } + * }) + * ``` + * + * @summary + * + * Create an inbound or outbound shipping method for a claim. */ export const createClaimShippingMethodWorkflow = createWorkflow( createClaimShippingMethodWorkflowId, - function (input: { - return_id?: string - claim_id?: string - shipping_option_id: string - custom_amount?: BigNumberInput | null - }): WorkflowResponse { + function (input: CreateClaimShippingMethodWorkflowInput): WorkflowResponse { const orderClaim: OrderClaimDTO = useRemoteQueryStep({ entry_point: "order_claim", fields: ["id", "status", "order_id", "canceled_at"], diff --git a/packages/core/core-flows/src/order/workflows/claim/remove-claim-add-item-action.ts b/packages/core/core-flows/src/order/workflows/claim/remove-claim-add-item-action.ts index 5e623954485df..405067651d59d 100644 --- a/packages/core/core-flows/src/order/workflows/claim/remove-claim-add-item-action.ts +++ b/packages/core/core-flows/src/order/workflows/claim/remove-claim-add-item-action.ts @@ -27,7 +27,57 @@ import { import { removeClaimShippingMethodWorkflow } from "./remove-claim-shipping-method" /** - * This step validates that new items can be removed from a claim. + * The data to validate that outbound (new) items can be removed from a claim. + */ +export type RemoveClaimAddItemActionValidationStepInput = { + /** + * The order's details. + */ + order: OrderDTO + /** + * The order claim's details. + */ + orderClaim: OrderClaimDTO + /** + * The order change's details. + */ + orderChange: OrderChangeDTO + /** + * The details of removing the outbound items. + */ + input: OrderWorkflow.DeleteOrderClaimItemActionWorkflowInput +} + +/** + * This step validates that outbound (new) items can be removed from a claim. + * If the order, claim, or order change is canceled, or the action is not adding an item, the step will throw an error. + * + * :::note + * + * You can retrieve an order, order claim, and order change details using [Query](https://docs.medusajs.com/learn/fundamentals/module-links/query), + * or [useQueryGraphStep](https://docs.medusajs.com/resources/references/medusa-workflows/steps/useQueryGraphStep). + * + * ::: + * + * @example + * const data = removeClaimAddItemActionValidationStep({ + * order: { + * id: "order_123", + * // other order details... + * }, + * orderChange: { + * id: "orch_123", + * // other order change details... + * }, + * orderClaim: { + * id: "claim_123", + * // other order claim details... + * }, + * input: { + * claim_id: "claim_123", + * action_id: "orchact_123", + * } + * }) */ export const removeClaimAddItemActionValidationStep = createStep( "remove-item-claim-add-action-validation", @@ -36,12 +86,7 @@ export const removeClaimAddItemActionValidationStep = createStep( orderChange, orderClaim, input, - }: { - order: OrderDTO - orderClaim: OrderClaimDTO - orderChange: OrderChangeDTO - input: OrderWorkflow.DeleteOrderClaimItemActionWorkflowInput - }) { + }: RemoveClaimAddItemActionValidationStepInput) { throwIfIsCancelled(order, "Order") throwIfIsCancelled(orderClaim, "Claim") throwIfOrderChangeIsNotActive({ orderChange }) @@ -60,9 +105,36 @@ export const removeClaimAddItemActionValidationStep = createStep( } ) +/** + * The data to remove outbound (new) items from a claim. + * + * @property action_id - The ID of the action associated with the outbound items. + * Every item has an `actions` property, whose value is an array of actions. + * You can find the action name `ITEM_ADD` using its `action` property, + * and use the value of its `id` property. + */ +export type RemoveAddItemClaimActionWorkflowInput = OrderWorkflow.DeleteOrderClaimItemActionWorkflowInput + export const removeAddItemClaimActionWorkflowId = "remove-item-claim-add-action" /** - * This workflow removes new items from a claim. + * This workflow removes outbound (new) items from a claim. It's used by the + * [Remove Outbound Items Admin API Route](https://docs.medusajs.com/api/admin#claims_deleteclaimsidoutbounditemsaction_id). + * + * You can use this workflow within your customizations or your own custom workflows, allowing you to remove outbound items from a claim + * in your custom flows. + * + * @example + * const { result } = await removeAddItemClaimActionWorkflow(container) + * .run({ + * input: { + * claim_id: "claim_123", + * action_id: "orchact_123", + * } + * }) + * + * @summary + * + * Remove outbound (new) items from a claim. */ export const removeAddItemClaimActionWorkflow = createWorkflow( removeAddItemClaimActionWorkflowId, diff --git a/packages/core/core-flows/src/order/workflows/claim/remove-claim-item-action.ts b/packages/core/core-flows/src/order/workflows/claim/remove-claim-item-action.ts index 4d6c03a8d7536..83d5ebe8b7453 100644 --- a/packages/core/core-flows/src/order/workflows/claim/remove-claim-item-action.ts +++ b/packages/core/core-flows/src/order/workflows/claim/remove-claim-item-action.ts @@ -24,7 +24,57 @@ import { } from "../../utils/order-validation" /** - * This step confirms that a claim's items can be removed. + * The data to validate that claim items can be removed. + */ +export type RemoveClaimItemActionValidationStepInput = { + /** + * The order's details. + */ + order: OrderDTO + /** + * The order claim's details. + */ + orderClaim: OrderClaimDTO + /** + * The order change's details. + */ + orderChange: OrderChangeDTO + /** + * The details of removing the claim items. + */ + input: OrderWorkflow.DeleteOrderClaimItemActionWorkflowInput +} + +/** + * This step confirms that a claim's items, added as order items, can be removed. + * If the order, claim, or order change is canceled, or the action is not claiming an item, the step will throw an error. + * + * :::note + * + * You can retrieve an order, order claim, and order change details using [Query](https://docs.medusajs.com/learn/fundamentals/module-links/query), + * or [useQueryGraphStep](https://docs.medusajs.com/resources/references/medusa-workflows/steps/useQueryGraphStep). + * + * ::: + * + * @example + * const data = removeClaimItemActionValidationStep({ + * order: { + * id: "order_123", + * // other order details... + * }, + * orderChange: { + * id: "orch_123", + * // other order change details... + * }, + * orderClaim: { + * id: "claim_123", + * // other order claim details... + * }, + * input: { + * claim_id: "claim_123", + * action_id: "orchact_123", + * } + * }) */ export const removeClaimItemActionValidationStep = createStep( "remove-item-claim-action-validation", @@ -33,12 +83,7 @@ export const removeClaimItemActionValidationStep = createStep( orderChange, orderClaim, input, - }: { - order: OrderDTO - orderClaim: OrderClaimDTO - orderChange: OrderChangeDTO - input: OrderWorkflow.DeleteOrderClaimItemActionWorkflowInput - }) { + }: RemoveClaimItemActionValidationStepInput) { throwIfIsCancelled(order, "Order") throwIfIsCancelled(orderClaim, "Claim") throwIfOrderChangeIsNotActive({ orderChange }) @@ -57,14 +102,37 @@ export const removeClaimItemActionValidationStep = createStep( } ) +/** + * The data to remove order items from a claim. + * + * @property action_id - The ID of the action associated with the outbound items. + * Every item has an `actions` property, whose value is an array of actions. + * You can find the action name `WRITE_OFF_ITEM` using its `action` property, + * and use the value of its `id` property. + */ +export type RemoveItemClaimActionWorkflowInput = OrderWorkflow.DeleteOrderClaimItemActionWorkflowInput + export const removeItemClaimActionWorkflowId = "remove-item-claim-action" /** - * This workflow removes claim items. + * This workflow removes order items from a claim. It's used by the + * [Remove Claim Item Admin API Route](https://docs.medusajs.com/api/admin#claims_deleteclaimsidclaimitemsaction_id). + * + * You can use this workflow within your customizations or your own custom workflows, allowing you to remove order items from a claim + * in your custom flows. + * + * @example + * const { result } = await removeItemClaimActionWorkflow(container) + * .run({ + * input: { + * claim_id: "claim_123", + * action_id: "orchact_123", + * } + * }) */ export const removeItemClaimActionWorkflow = createWorkflow( removeItemClaimActionWorkflowId, function ( - input: WorkflowData + input: WorkflowData ): WorkflowResponse { const orderClaim: OrderClaimDTO = useRemoteQueryStep({ entry_point: "order_claim", diff --git a/packages/core/core-flows/src/order/workflows/claim/remove-claim-shipping-method.ts b/packages/core/core-flows/src/order/workflows/claim/remove-claim-shipping-method.ts index 8795a39967fd8..80dc9f565a468 100644 --- a/packages/core/core-flows/src/order/workflows/claim/remove-claim-shipping-method.ts +++ b/packages/core/core-flows/src/order/workflows/claim/remove-claim-shipping-method.ts @@ -23,8 +23,51 @@ import { throwIfOrderChangeIsNotActive, } from "../../utils/order-validation" +/** + * The data to validate that a claim's shipping method can be removed. + */ +export type RemoveClaimShippingMethodValidationStepInput = { + /** + * The order claim's details. + */ + orderClaim: OrderClaimDTO + /** + * The order change's details. + */ + orderChange: OrderChangeDTO + /** + * The details of removing the shipping method. + */ + input: Pick +} + /** * This step validates that a claim's shipping method can be removed. + * If the claim or order change is canceled, the shipping method doesn't + * exist in the claim, or the action is not adding a shipping method, the step will throw an error. + * + * :::note + * + * You can retrieve an order claim and order change details using [Query](https://docs.medusajs.com/learn/fundamentals/module-links/query), + * or [useQueryGraphStep](https://docs.medusajs.com/resources/references/medusa-workflows/steps/useQueryGraphStep). + * + * ::: + * + * @example + * const data = removeClaimShippingMethodValidationStep({ + * orderChange: { + * id: "orch_123", + * // other order change details... + * }, + * orderClaim: { + * id: "claim_123", + * // other order claim details... + * }, + * input: { + * claim_id: "claim_123", + * action_id: "orchact_123", + * } + * }) */ export const removeClaimShippingMethodValidationStep = createStep( "validate-remove-claim-shipping-method", @@ -32,11 +75,7 @@ export const removeClaimShippingMethodValidationStep = createStep( orderChange, orderClaim, input, - }: { - input: { claim_id: string; action_id: string } - orderClaim: OrderClaimDTO - orderChange: OrderChangeDTO - }) { + }: RemoveClaimShippingMethodValidationStepInput) { throwIfIsCancelled(orderClaim, "Claim") throwIfOrderChangeIsNotActive({ orderChange }) @@ -59,7 +98,25 @@ export const removeClaimShippingMethodValidationStep = createStep( export const removeClaimShippingMethodWorkflowId = "remove-claim-shipping-method" /** - * This workflow removes the shipping method of a claim. + * This workflow removes an inbound (return) or outbound (delivery of new items) shipping method of a claim. + * It's used by the [Remove Inbound Shipping Method](https://docs.medusajs.com/api/admin#claims_deleteclaimsidinboundshippingmethodaction_id), + * or [Remove Outbound Shipping Method](https://docs.medusajs.com/api/admin#claims_deleteclaimsidoutboundshippingmethodaction_id) Admin API Routes. + * + * You can use this workflow within your customizations or your own custom workflows, allowing you to remove shipping methods from a claim + * in your own custom flows. + * + * @example + * const { result } = await removeClaimShippingMethodWorkflow(container) + * .run({ + * input: { + * claim_id: "claim_123", + * action_id: "orchact_123", + * } + * }) + * + * @summary + * + * Remove an inbound or outbound shipping method from a claim. */ export const removeClaimShippingMethodWorkflow = createWorkflow( removeClaimShippingMethodWorkflowId, diff --git a/packages/core/core-flows/src/order/workflows/claim/update-claim-add-item.ts b/packages/core/core-flows/src/order/workflows/claim/update-claim-add-item.ts index a0c2b2f5bba5b..fa3468de65d48 100644 --- a/packages/core/core-flows/src/order/workflows/claim/update-claim-add-item.ts +++ b/packages/core/core-flows/src/order/workflows/claim/update-claim-add-item.ts @@ -25,7 +25,61 @@ import { } from "../../utils/order-validation" /** - * This step validates that a claim's new item can be updated. + * The data to validate that a claim's outbound item can be updated. + */ +export type UpdateClaimAddNewItemValidationStepInput = { + /** + * The order's details. + */ + order: OrderDTO + /** + * The order claim's details. + */ + orderClaim: OrderClaimDTO + /** + * The order change's details. + */ + orderChange: OrderChangeDTO + /** + * The details of updating the outbound item. + */ + input: OrderWorkflow.UpdateClaimAddNewItemWorkflowInput +} + +/** + * This step validates that a claim's new or outbound item can be updated. + * If the order, claim, or order change is canceled, no action is adding the item, + * or the action is not adding an outbound item, the step will throw an error. + * + * :::note + * + * You can retrieve an order, order claim, and order change details using [Query](https://docs.medusajs.com/learn/fundamentals/module-links/query), + * or [useQueryGraphStep](https://docs.medusajs.com/resources/references/medusa-workflows/steps/useQueryGraphStep). + * + * ::: + * + * @example + * const data = updateClaimAddItemValidationStep({ + * order: { + * id: "order_123", + * // other order details... + * }, + * orderChange: { + * id: "orch_123", + * // other order change details... + * }, + * orderClaim: { + * id: "claim_123", + * // other order claim details... + * }, + * input: { + * claim_id: "claim_123", + * action_id: "orchact_123", + * data: { + * quantity: 1, + * } + * } + * }) */ export const updateClaimAddItemValidationStep = createStep( "update-claim-add-item-validation", @@ -35,12 +89,7 @@ export const updateClaimAddItemValidationStep = createStep( orderChange, orderClaim, input, - }: { - order: OrderDTO - orderClaim: OrderClaimDTO - orderChange: OrderChangeDTO - input: OrderWorkflow.UpdateClaimAddNewItemWorkflowInput - }, + }: UpdateClaimAddNewItemValidationStepInput, context ) { throwIfIsCancelled(order, "Order") @@ -63,7 +112,27 @@ export const updateClaimAddItemValidationStep = createStep( export const updateClaimAddItemWorkflowId = "update-claim-add-item" /** - * This workflow updates a claim's new item. + * This workflow updates a claim's new or outbound item. It's used by the + * [Update Outbound Item API Route](https://docs.medusajs.com/api/admin#claims_postclaimsidoutbounditemsaction_id). + * + * You can use this workflow within your customizations or your own custom workflows, allowing you to update a claim's new or outbound item + * in your custom flows. + * + * @example + * const { result } = await updateClaimAddItemWorkflow(container) + * .run({ + * input: { + * claim_id: "claim_123", + * action_id: "orchact_123", + * data: { + * quantity: 1, + * } + * } + * }) + * + * @summary + * + * Update a claim's new or outbound item. */ export const updateClaimAddItemWorkflow = createWorkflow( updateClaimAddItemWorkflowId, diff --git a/packages/core/core-flows/src/order/workflows/claim/update-claim-item.ts b/packages/core/core-flows/src/order/workflows/claim/update-claim-item.ts index e9f53f8fec10e..341c654c792e0 100644 --- a/packages/core/core-flows/src/order/workflows/claim/update-claim-item.ts +++ b/packages/core/core-flows/src/order/workflows/claim/update-claim-item.ts @@ -25,7 +25,61 @@ import { } from "../../utils/order-validation" /** - * This step validates that a claim's item can be updated. + * The data to validate that a claim's item can be updated. + */ +export type UpdateClaimItemValidationStepInput = { + /** + * The order's details. + */ + order: OrderDTO + /** + * The order claim's details. + */ + orderClaim: OrderClaimDTO + /** + * The order change's details. + */ + orderChange: OrderChangeDTO + /** + * The details of updating the item. + */ + input: OrderWorkflow.UpdateClaimItemWorkflowInput +} + +/** + * This step validates that a claim's item (added as an order item) can be updated. + * If the order, claim, or order change is canceled, no action is claiming the item, + * or the action is not claiming the item, the step will throw an error. + * + * :::note + * + * You can retrieve an order, order claim, and order change details using [Query](https://docs.medusajs.com/learn/fundamentals/module-links/query), + * or [useQueryGraphStep](https://docs.medusajs.com/resources/references/medusa-workflows/steps/useQueryGraphStep). + * + * ::: + * + * @example + * const data = updateClaimItemValidationStep({ + * order: { + * id: "order_123", + * // other order details... + * }, + * orderChange: { + * id: "orch_123", + * // other order change details... + * }, + * orderClaim: { + * id: "claim_123", + * // other order claim details... + * }, + * input: { + * claim_id: "claim_123", + * action_id: "orchact_123", + * data: { + * quantity: 1, + * } + * } + * }) */ export const updateClaimItemValidationStep = createStep( "update-claim-item-validation", @@ -35,12 +89,7 @@ export const updateClaimItemValidationStep = createStep( orderChange, orderClaim, input, - }: { - order: OrderDTO - orderClaim: OrderClaimDTO - orderChange: OrderChangeDTO - input: OrderWorkflow.UpdateClaimItemWorkflowInput - }, + }: UpdateClaimItemValidationStepInput, context ) { throwIfIsCancelled(order, "Order") @@ -63,7 +112,27 @@ export const updateClaimItemValidationStep = createStep( export const updateClaimItemWorkflowId = "update-claim-item" /** - * This workflow updates a claim item. + * This workflow updates a claim item, added to the claim from an order item. + * It's used by the [Update Claim Item Admin API Route](https://docs.medusajs.com/api/admin#claims_postclaimsidclaimitemsaction_id). + * + * You can use this workflow within your customizations or your own custom workflows, allowing you to update a claim item + * in your custom flows. + * + * @example + * const { result } = await updateClaimItemWorkflow(container) + * .run({ + * input: { + * claim_id: "claim_123", + * action_id: "orchact_123", + * data: { + * quantity: 1, + * } + * } + * }) + * + * @summary + * + * Update a claim item, added to the claim from an order item. */ export const updateClaimItemWorkflow = createWorkflow( updateClaimItemWorkflowId, diff --git a/packages/core/core-flows/src/order/workflows/claim/update-claim-shipping-method.ts b/packages/core/core-flows/src/order/workflows/claim/update-claim-shipping-method.ts index 92a6a99a87ed1..6a0620b1fc2e6 100644 --- a/packages/core/core-flows/src/order/workflows/claim/update-claim-shipping-method.ts +++ b/packages/core/core-flows/src/order/workflows/claim/update-claim-shipping-method.ts @@ -27,8 +27,51 @@ import { } from "../../utils/order-validation" import { prepareShippingMethodUpdate } from "../../utils/prepare-shipping-method" +/** + * The data to validate that a claim's shipping method can be updated. + */ +export type UpdateClaimShippingMethodValidationStepInput = { + /** + * The order claim's details. + */ + orderClaim: OrderClaimDTO + /** + * The order change's details. + */ + orderChange: OrderChangeDTO + /** + * The details of updating the shipping method. + */ + input: Pick +} + /** * This step validates that a claim's shipping method can be updated. + * If the claim is canceled, the order change is not active, the shipping method isn't added to the claim, + * or the action is not adding a shipping method, the step will throw an error. + * + * :::note + * + * You can retrieve an order claim and order change details using [Query](https://docs.medusajs.com/learn/fundamentals/module-links/query), + * or [useQueryGraphStep](https://docs.medusajs.com/resources/references/medusa-workflows/steps/useQueryGraphStep). + * + * ::: + * + * @example + * const data = updateClaimShippingMethodValidationStep({ + * orderChange: { + * id: "orch_123", + * // other order change details... + * }, + * orderClaim: { + * id: "claim_123", + * // other order claim details... + * }, + * input: { + * claim_id: "claim_123", + * action_id: "orchact_123", + * } + * }) */ export const updateClaimShippingMethodValidationStep = createStep( "validate-update-claim-shipping-method", @@ -36,11 +79,7 @@ export const updateClaimShippingMethodValidationStep = createStep( orderChange, orderClaim, input, - }: { - input: { claim_id: string; action_id: string } - orderClaim: OrderClaimDTO - orderChange: OrderChangeDTO - }) { + }: UpdateClaimShippingMethodValidationStepInput) { throwIfIsCancelled(orderClaim, "Claim") throwIfOrderChangeIsNotActive({ orderChange }) @@ -63,7 +102,28 @@ export const updateClaimShippingMethodValidationStep = createStep( export const updateClaimShippingMethodWorkflowId = "update-claim-shipping-method" /** - * This workflow updates a claim's shipping method. + * This workflow updates a claim's inbound (return) or outbound (delivery of new items) shipping method. + * It's used by the [Update Inbound Shipping Admin API Route](https://docs.medusajs.com/api/admin#claims_postclaimsidinboundshippingmethodaction_id), + * and the [Update Outbound Shipping Admin API Route](https://docs.medusajs.com/api/admin#claims_postclaimsidoutboundshippingmethodaction_id). + * + * You can use this workflow within your customizations or your own custom workflows, allowing you to update a claim's shipping method + * in your own custom flows. + * + * @example + * const { result } = await updateClaimShippingMethodWorkflow(container) + * .run({ + * input: { + * claim_id: "claim_123", + * action_id: "orchact_123", + * data: { + * custom_amount: 10, + * } + * } + * }) + * + * @summary + * + * Update an inbound or outbound shipping method of a claim. */ export const updateClaimShippingMethodWorkflow = createWorkflow( updateClaimShippingMethodWorkflowId, diff --git a/packages/core/core-flows/src/order/workflows/complete-orders.ts b/packages/core/core-flows/src/order/workflows/complete-orders.ts index 3285a2947cdb4..c557cbcd20847 100644 --- a/packages/core/core-flows/src/order/workflows/complete-orders.ts +++ b/packages/core/core-flows/src/order/workflows/complete-orders.ts @@ -27,7 +27,7 @@ export const completeOrderWorkflowId = "complete-order-workflow" * This workflow has a hook that allows you to perform custom actions on the completed orders. For example, you can pass under `additional_data` custom data that * allows you to update custom data models linked to the orders. * - * You can also use this workflow within your own custom workflows, allowing you to wrap custom logic around order completion. + * You can also use this workflow within your customizations or your own custom workflows, allowing you to wrap custom logic around order completion. * * @example * const { result } = await completeOrderWorkflow(container) diff --git a/packages/core/core-flows/src/order/workflows/create-fulfillment.ts b/packages/core/core-flows/src/order/workflows/create-fulfillment.ts index c5801024e4014..4b076d46c5621 100644 --- a/packages/core/core-flows/src/order/workflows/create-fulfillment.ts +++ b/packages/core/core-flows/src/order/workflows/create-fulfillment.ts @@ -40,17 +40,51 @@ import { } from "../utils/order-validation" /** - * This step validates that a fulfillment can be created for an order. + * The data to validate the order fulfillment creation. + */ +export type CreateFulfillmentValidateOrderStepInput = { + /** + * The order to create the fulfillment for. + */ + order: OrderDTO + /** + * The items to fulfill. + */ + inputItems: OrderWorkflow.CreateOrderFulfillmentWorkflowInput["items"] +} + +/** + * This step validates that a fulfillment can be created for an order. If the order + * is canceled, the items don't exist in the order, or the items aren't grouped by + * shipping requirement, the step throws an error. + * + * :::note + * + * You can retrieve an order's details using [Query](https://docs.medusajs.com/learn/fundamentals/module-links/query), + * or [useQueryGraphStep](https://docs.medusajs.com/resources/references/medusa-workflows/steps/useQueryGraphStep). + * + * ::: + * + * @example + * const data = createFulfillmentValidateOrder({ + * order: { + * id: "order_123", + * // other order details... + * }, + * inputItems: [ + * { + * id: "orli_123", + * quantity: 1, + * } + * ] + * }) */ export const createFulfillmentValidateOrder = createStep( "create-fulfillment-validate-order", ({ order, inputItems, - }: { - order: OrderDTO - inputItems: OrderWorkflow.CreateOrderFulfillmentWorkflowInput["items"] - }) => { + }: CreateFulfillmentValidateOrderStepInput) => { throwIfOrderIsCancelled({ order }) throwIfItemsDoesNotExistsInOrder({ order, inputItems }) throwIfItemsAreNotGroupedByShippingRequirement({ order, inputItems }) @@ -247,7 +281,7 @@ export const createOrderFulfillmentWorkflowId = "create-order-fulfillment" * This workflow has a hook that allows you to perform custom actions on the created fulfillment. For example, you can pass under `additional_data` custom data that * allows you to create custom data models linked to the fulfillment. * - * You can also use this workflow within your own custom workflows, allowing you to wrap custom logic around creating a fulfillment. + * You can also use this workflow within your customizations or your own custom workflows, allowing you to wrap custom logic around creating a fulfillment. * * @example * const { result } = await createOrderFulfillmentWorkflow(container) diff --git a/packages/core/core-flows/src/order/workflows/create-or-update-order-payment-collection.ts b/packages/core/core-flows/src/order/workflows/create-or-update-order-payment-collection.ts index d83c3e01f79da..a74471bce2684 100644 --- a/packages/core/core-flows/src/order/workflows/create-or-update-order-payment-collection.ts +++ b/packages/core/core-flows/src/order/workflows/create-or-update-order-payment-collection.ts @@ -15,10 +15,40 @@ import { useRemoteQueryStep } from "../../common" import { updatePaymentCollectionStep } from "../../payment-collection" import { createOrderPaymentCollectionWorkflow } from "./create-order-payment-collection" +/** + * The details of the order payment collection to create or update. + */ +export type CreateOrUpdateOrderPaymentCollectionInput = { + /** + * The order to create or update payment collection for. + */ + order_id: string + /** + * The amount to charge. It can't be greater than the + * pending amount of the order. The order's payment collection + * will be created or updated with this amount. + * If no amount is set, the payment collection's amount is set to `0`. + */ + amount?: number +} + export const createOrUpdateOrderPaymentCollectionWorkflowId = "create-or-update-order-payment-collection" /** - * This workflow creates or updates payment collection for an order. + * This workflow creates or updates payment collection for an order. It's used by other order-related workflows, + * such as {@link createOrderPaymentCollectionWorkflow} to update an order's payment collections based on changes made to the order. + * + * You can use this workflow within your customizations or your own custom workflows, allowing you to wrap custom logic around + * creating or updating payment collections for an order. + * + * @example + * const { result } = await createOrUpdateOrderPaymentCollectionWorkflow(container) + * .run({ + * input: { + * order_id: "order_123", + * amount: 20 + * } + * }) */ export const createOrUpdateOrderPaymentCollectionWorkflow = createWorkflow( createOrUpdateOrderPaymentCollectionWorkflowId, diff --git a/packages/core/core-flows/src/order/workflows/create-order-change-actions.ts b/packages/core/core-flows/src/order/workflows/create-order-change-actions.ts index 98dc0477d3442..d8a16755383af 100644 --- a/packages/core/core-flows/src/order/workflows/create-order-change-actions.ts +++ b/packages/core/core-flows/src/order/workflows/create-order-change-actions.ts @@ -12,7 +12,15 @@ import { createEntitiesStep } from "../../common/steps/create-entities" export const createOrderChangeActionsWorkflowId = "create-order-change-actions" /** - * This workflow creates order change actions. + * This workflow creates order change actions. It's used by other order-related workflows, + * such as {@link requestItemReturnWorkflow} to create an order change action based on changes made to the order. + * + * You can use this workflow within your customizations or your own custom workflows, allowing you to wrap custom logic around + * creating an order change action. + * + * @summary + * + * Create an order change action. */ export const createOrderChangeActionsWorkflow = createWorkflow( createOrderChangeActionsWorkflowId, diff --git a/packages/core/core-flows/src/order/workflows/create-order-change.ts b/packages/core/core-flows/src/order/workflows/create-order-change.ts index 10087920e9934..637a41aa4436d 100644 --- a/packages/core/core-flows/src/order/workflows/create-order-change.ts +++ b/packages/core/core-flows/src/order/workflows/create-order-change.ts @@ -9,6 +9,13 @@ import { createOrderChangeStep } from "../steps" export const createOrderChangeWorkflowId = "create-order-change" /** * This workflow creates an order change. + * + * You can use this workflow within your customizations or your own custom workflows, allowing you to wrap custom logic around + * creating an order change. + * + * @summary + * + * Create an order change. */ export const createOrderChangeWorkflow = createWorkflow( createOrderChangeWorkflowId, diff --git a/packages/core/core-flows/src/order/workflows/create-order-payment-collection.ts b/packages/core/core-flows/src/order/workflows/create-order-payment-collection.ts index b79c9476b8ac9..663849617ff8e 100644 --- a/packages/core/core-flows/src/order/workflows/create-order-payment-collection.ts +++ b/packages/core/core-flows/src/order/workflows/create-order-payment-collection.ts @@ -8,18 +8,46 @@ import { import { createRemoteLinkStep, useRemoteQueryStep } from "../../common" import { createPaymentCollectionsStep } from "../../cart" +/** + * The details of the payment collection to create. + */ +export type CreateOrderPaymentCollectionWorkflowInput = { + /** + * The id of the order for which to create a payment collection. + */ + order_id: string + /** + * The amount of the payment collection. + */ + amount: number +} + export const createOrderPaymentCollectionWorkflowId = "create-order-payment-collection" /** - * This workflow creates a payment collection for an order. + * This workflow creates a payment collection for an order. It's used by the + * [Create Payment Collection Admin API Route](https://docs.medusajs.com/api/admin#payment-collections_postpaymentcollections). + * + * You can use this workflow within your customizations or your own custom workflows, allowing you to wrap custom logic around + * creating a payment collection for an order. + * + * @example + * const { result } = await createOrderPaymentCollectionWorkflow(container) + * .run({ + * input: { + * order_id: "order_123", + * amount: 10, + * } + * }) + * + * @summary + * + * Create a payment collection for an order. */ export const createOrderPaymentCollectionWorkflow = createWorkflow( createOrderPaymentCollectionWorkflowId, ( - input: WorkflowData<{ - order_id: string - amount: number - }> + input: WorkflowData ) => { const order = useRemoteQueryStep({ entry_point: "order", diff --git a/packages/core/core-flows/src/order/workflows/create-order.ts b/packages/core/core-flows/src/order/workflows/create-order.ts index 31247ef820bc0..745064484ee7b 100644 --- a/packages/core/core-flows/src/order/workflows/create-order.ts +++ b/packages/core/core-flows/src/order/workflows/create-order.ts @@ -86,7 +86,7 @@ export const createOrdersWorkflowId = "create-orders" * This workflow has a hook that allows you to perform custom actions on the created order. For example, you can pass under `additional_data` custom data that * allows you to create custom data models linked to the order. * - * You can also use this workflow within your own custom workflows, allowing you to wrap custom logic around creating an order. For example, + * You can also use this workflow within your customizations or your own custom workflows, allowing you to wrap custom logic around creating an order. For example, * you can create a workflow that imports orders from an external system, then uses this workflow to create the orders in Medusa. * * @example diff --git a/packages/core/core-flows/src/order/workflows/create-shipment.ts b/packages/core/core-flows/src/order/workflows/create-shipment.ts index c300553b5be2d..9aa03fae4d102 100644 --- a/packages/core/core-flows/src/order/workflows/create-shipment.ts +++ b/packages/core/core-flows/src/order/workflows/create-shipment.ts @@ -22,17 +22,55 @@ import { } from "../utils/order-validation" /** - * This step validates that a shipment can be created for an order. + * The data to validate the order shipment creation. + */ +export type CreateShipmentValidateOrderStepInput = { + /** + * The order to create the shipment for. + */ + order: OrderDTO + /** + * The shipment creation details. + */ + input: OrderWorkflow.CreateOrderShipmentWorkflowInput +} + +/** + * This step validates that a shipment can be created for an order. If the order is cancelled, + * the items don't exist in the order, or the fulfillment doesn't exist in the order, + * the step will throw an error. + * + * :::note + * + * You can retrieve an order's details using [Query](https://docs.medusajs.com/learn/fundamentals/module-links/query), + * or [useQueryGraphStep](https://docs.medusajs.com/resources/references/medusa-workflows/steps/useQueryGraphStep). + * + * ::: + * + * @example + * const data = createShipmentValidateOrder({ + * order: { + * id: "order_123", + * // other order details... + * }, + * input: { + * order_id: "order_123", + * fulfillment_id: "ful_123", + * items: [ + * { + * id: "orli_123", + * quantity: 1 + * } + * ] + * } + * }) */ export const createShipmentValidateOrder = createStep( "create-shipment-validate-order", ({ order, input, - }: { - order: OrderDTO - input: OrderWorkflow.CreateOrderShipmentWorkflowInput - }) => { + }: CreateShipmentValidateOrderStepInput) => { const inputItems = input.items throwIfOrderIsCancelled({ order }) @@ -87,7 +125,7 @@ export const createOrderShipmentWorkflowId = "create-order-shipment" * This workflow has a hook that allows you to perform custom actions on the created shipment. For example, you can pass under `additional_data` custom data that * allows you to create custom data models linked to the shipment. * - * You can also use this workflow within your own custom workflows, allowing you to wrap custom logic around creating a shipment. + * You can also use this workflow within your customizations or your own custom workflows, allowing you to wrap custom logic around creating a shipment. * * @example * const { result } = await createOrderShipmentWorkflow(container) diff --git a/packages/core/core-flows/src/order/workflows/decline-order-change.ts b/packages/core/core-flows/src/order/workflows/decline-order-change.ts index 4025eb845a26e..b5807318b025b 100644 --- a/packages/core/core-flows/src/order/workflows/decline-order-change.ts +++ b/packages/core/core-flows/src/order/workflows/decline-order-change.ts @@ -5,6 +5,13 @@ import { declineOrderChangeStep } from "../steps" export const declineOrderChangeWorkflowId = "decline-order-change" /** * This workflow declines an order change. + * + * You can use this workflow within your customizations or your own custom workflows, allowing you to wrap custom logic around + * declining an order change. + * + * @summary + * + * Decline an order change. */ export const declineOrderChangeWorkflow = createWorkflow( declineOrderChangeWorkflowId, diff --git a/packages/core/core-flows/src/order/workflows/delete-order-change-actions.ts b/packages/core/core-flows/src/order/workflows/delete-order-change-actions.ts index 6a26c0021b6af..faf9d2f5e6aeb 100644 --- a/packages/core/core-flows/src/order/workflows/delete-order-change-actions.ts +++ b/packages/core/core-flows/src/order/workflows/delete-order-change-actions.ts @@ -1,13 +1,30 @@ import { WorkflowData, createWorkflow } from "@medusajs/framework/workflows-sdk" import { deleteOrderChangeActionsStep } from "../steps" +/** + * The details of the order change actions to delete. + */ +export type DeleteOrderChangeActionsWorkflowInput = { + /** + * The IDs of the order change actions to delete. + */ + ids: string[] +} + export const deleteOrderChangeActionsWorkflowId = "delete-order-change-actions" /** * This workflow deletes one or more order change actions. + * + * You can use this workflow within your customizations or your own custom workflows, allowing you to wrap custom logic around + * deleting an order change action. + * + * @summary + * + * Delete one or more order change actions. */ export const deleteOrderChangeActionsWorkflow = createWorkflow( deleteOrderChangeActionsWorkflowId, - (input: WorkflowData<{ ids: string[] }>): WorkflowData => { + (input: WorkflowData): WorkflowData => { deleteOrderChangeActionsStep(input) } ) diff --git a/packages/core/core-flows/src/order/workflows/delete-order-change.ts b/packages/core/core-flows/src/order/workflows/delete-order-change.ts index 1cb8e80d2499d..3472807a0662a 100644 --- a/packages/core/core-flows/src/order/workflows/delete-order-change.ts +++ b/packages/core/core-flows/src/order/workflows/delete-order-change.ts @@ -1,13 +1,30 @@ import { WorkflowData, createWorkflow } from "@medusajs/framework/workflows-sdk" import { deleteOrderChangesStep } from "../steps" +/** + * The details of the order changes to delete. + */ +export type DeleteOrderChangeWorkflowInput = { + /** + * The IDs of the order changes to delete. + */ + ids: string[] +} + export const deleteOrderChangeWorkflowId = "delete-order-change" /** * This workflow deletes one or more order changes. + * + * You can use this workflow within your customizations or your own custom workflows, allowing you to wrap custom logic around + * deleting an order change. + * + * @summary + * + * Delete one or more order changes. */ export const deleteOrderChangeWorkflow = createWorkflow( deleteOrderChangeWorkflowId, - (input: WorkflowData<{ ids: string[] }>): WorkflowData => { + (input: WorkflowData): WorkflowData => { deleteOrderChangesStep(input) } ) diff --git a/packages/core/core-flows/src/order/workflows/delete-order-payment-collection.ts b/packages/core/core-flows/src/order/workflows/delete-order-payment-collection.ts index 9eb5b8f28f30b..11794dfd4747b 100644 --- a/packages/core/core-flows/src/order/workflows/delete-order-payment-collection.ts +++ b/packages/core/core-flows/src/order/workflows/delete-order-payment-collection.ts @@ -26,14 +26,40 @@ export const throwUnlessStatusIsNotPaid = createStep( } ) +/** + * The details of the payment collection to delete. + */ +export type DeleteOrderPaymentCollectionsInput = { + /** + * The ID of the payment collection to delete. + */ + id: string +} + export const deleteOrderPaymentCollectionsId = "delete-order-payment-collectionworkflow" /** - * This workflow deletes one or more invites. + * This workflow deletes one or more payment collections of an order. It's used by the + * [Delete Payment Collection API Route](https://docs.medusajs.com/api/admin#payment-collections_deletepaymentcollectionsid). + * + * You can use this workflow within your customizations or your own custom workflows, allowing you to wrap custom logic around + * deleting a payment collection of an order. + * + * @example + * const { result } = await deleteOrderPaymentCollections(container) + * .run({ + * input: { + * id: "order_123" + * } + * }) + * + * @summary + * + * Delete a payment collection of an order. */ export const deleteOrderPaymentCollections = createWorkflow( deleteOrderPaymentCollectionsId, - (input: WorkflowData<{ id: string }>): WorkflowData => { + (input: WorkflowData): WorkflowData => { const paymentCollection = useRemoteQueryStep({ entry_point: "payment_collection", fields: ["id", "status"], diff --git a/packages/core/core-flows/src/order/workflows/exchange/begin-order-exchange.ts b/packages/core/core-flows/src/order/workflows/exchange/begin-order-exchange.ts index 9d03ceb3177d4..3ea521f7a68c7 100644 --- a/packages/core/core-flows/src/order/workflows/exchange/begin-order-exchange.ts +++ b/packages/core/core-flows/src/order/workflows/exchange/begin-order-exchange.ts @@ -15,19 +15,61 @@ import { createOrderChangeStep } from "../../steps/create-order-change" import { createOrderExchangesStep } from "../../steps/exchange/create-exchange" import { throwIfOrderIsCancelled } from "../../utils/order-validation" +/** + * The data to validate that an exchange can be requested for an order. + */ +export type BeginOrderExchangeValidationStepInput = { + /** + * The order's details. + */ + order: OrderDTO +} + /** * This step validates that an exchange can be requested for an order. + * If the order is canceled, the step will throw an error. + * + * :::note + * + * You can retrieve an order's details using [Query](https://docs.medusajs.com/learn/fundamentals/module-links/query), + * or [useQueryGraphStep](https://docs.medusajs.com/resources/references/medusa-workflows/steps/useQueryGraphStep). + * + * ::: + * + * @example + * const data = beginOrderExchangeValidationStep({ + * order: { + * id: "order_123", + * // other order details... + * }, + * }) */ export const beginOrderExchangeValidationStep = createStep( "begin-exchange-order-validation", - async function ({ order }: { order: OrderDTO }) { + async function ({ order }: BeginOrderExchangeValidationStepInput) { throwIfOrderIsCancelled({ order }) } ) export const beginExchangeOrderWorkflowId = "begin-exchange-order" /** - * This workflow requests an order exchange. + * This workflow requests an order exchange. It's used by the + * [Create Exchange Admin API Route](https://docs.medusajs.com/api/admin#exchanges_postexchanges). + * + * You can use this workflow within your customizations or your own custom workflows, allowing you to request an exchange + * for an order in your custom flow. + * + * @example + * const { result } = await beginExchangeOrderWorkflow(container) + * .run({ + * input: { + * order_id: "order_123", + * } + * }) + * + * @summary + * + * Request an order exchange. */ export const beginExchangeOrderWorkflow = createWorkflow( beginExchangeOrderWorkflowId, diff --git a/packages/core/core-flows/src/order/workflows/exchange/cancel-begin-order-exchange.ts b/packages/core/core-flows/src/order/workflows/exchange/cancel-begin-order-exchange.ts index 532ea5e97a796..a937da4360458 100644 --- a/packages/core/core-flows/src/order/workflows/exchange/cancel-begin-order-exchange.ts +++ b/packages/core/core-flows/src/order/workflows/exchange/cancel-begin-order-exchange.ts @@ -23,12 +23,50 @@ import { throwIfOrderChangeIsNotActive, } from "../../utils/order-validation" -export type CancelBeginOrderExchangeWorkflowInput = { - exchange_id: string +/** + * The data to validate that a requested exchange can be canceled. + */ +export type CancelBeginOrderExchangeValidationStepInput = { + /** + * The order's details. + */ + order: OrderDTO + /** + * The order exchange's details. + */ + orderExchange: OrderExchangeDTO + /** + * The order change's details. + */ + orderChange: OrderChangeDTO } /** * This step validates that a requested exchange can be canceled. + * If the order or exchange is canceled, or the order change is not active, the step will throw an error. + * + * :::note + * + * You can retrieve an order, order exchange, and order change details using [Query](https://docs.medusajs.com/learn/fundamentals/module-links/query), + * or [useQueryGraphStep](https://docs.medusajs.com/resources/references/medusa-workflows/steps/useQueryGraphStep). + * + * ::: + * + * @example + * const data = cancelBeginOrderExchangeValidationStep({ + * order: { + * id: "order_123", + * // other order details... + * }, + * orderChange: { + * id: "orch_123", + * // other order change details... + * }, + * orderExchange: { + * id: "exchange_123", + * // other order exchange details... + * }, + * }) */ export const cancelBeginOrderExchangeValidationStep = createStep( "validate-cancel-begin-order-exchange", @@ -36,20 +74,42 @@ export const cancelBeginOrderExchangeValidationStep = createStep( order, orderChange, orderExchange, - }: { - order: OrderDTO - orderExchange: OrderExchangeDTO - orderChange: OrderChangeDTO - }) { + }: CancelBeginOrderExchangeValidationStepInput) { throwIfIsCancelled(order, "Order") throwIfIsCancelled(orderExchange, "Exchange") throwIfOrderChangeIsNotActive({ orderChange }) } ) +/** + * The details to cancel a requested order exchange. + */ +export type CancelBeginOrderExchangeWorkflowInput = { + /** + * The ID of the exchange to cancel. + */ + exchange_id: string +} + export const cancelBeginOrderExchangeWorkflowId = "cancel-begin-order-exchange" /** - * This workflow cancels a requested order exchange. + * This workflow cancels a requested order exchange. It's used by the + * [Cancel Exchange Admin API Route](https://docs.medusajs.com/api/admin#exchanges_deleteexchangesidrequest). + * + * You can use this workflow within your customizations or your own custom workflows, allowing you to cancel an exchange + * for an order in your custom flow. + * + * @example + * const { result } = await cancelBeginOrderExchangeWorkflow(container) + * .run({ + * input: { + * exchange_id: "exchange_123", + * } + * }) + * + * @summary + * + * Cancel a requested order exchange. */ export const cancelBeginOrderExchangeWorkflow = createWorkflow( cancelBeginOrderExchangeWorkflowId, diff --git a/packages/core/core-flows/src/order/workflows/exchange/cancel-exchange.ts b/packages/core/core-flows/src/order/workflows/exchange/cancel-exchange.ts index 0ae849915010a..fdec827791c33 100644 --- a/packages/core/core-flows/src/order/workflows/exchange/cancel-exchange.ts +++ b/packages/core/core-flows/src/order/workflows/exchange/cancel-exchange.ts @@ -18,17 +18,47 @@ import { cancelOrderExchangeStep } from "../../steps" import { throwIfIsCancelled } from "../../utils/order-validation" import { cancelReturnWorkflow } from "../return/cancel-return" +/** + * The data to validate that an exchange can be canceled. + */ +export type CancelExchangeValidateOrderStepInput = { + /** + * The order exchange's details. + */ + orderExchange: OrderExchangeDTO + /** + * The details of canceling the exchange. + */ + input: OrderWorkflow.CancelOrderExchangeWorkflowInput +} + /** * This step validates that an exchange can be canceled. + * If the exchange is canceled, or any of the fulfillments are not canceled, the step will throw an error. + * + * :::note + * + * You can retrieve an order exchange's details using [Query](https://docs.medusajs.com/learn/fundamentals/module-links/query), + * or [useQueryGraphStep](https://docs.medusajs.com/resources/references/medusa-workflows/steps/useQueryGraphStep). + * + * ::: + * + * @example + * const data = cancelExchangeValidateOrder({ + * orderExchange: { + * id: "exchange_123", + * // other order exchange details... + * }, + * input: { + * exchange_id: "exchange_123", + * } + * }) */ export const cancelExchangeValidateOrder = createStep( "validate-exchange", ({ orderExchange, - }: { - orderExchange: OrderExchangeDTO - input: OrderWorkflow.CancelOrderExchangeWorkflowInput - }) => { + }: CancelExchangeValidateOrderStepInput) => { const orderExchange_ = orderExchange as OrderExchangeDTO & { fulfillments: FulfillmentDTO[] } @@ -57,7 +87,23 @@ export const cancelExchangeValidateOrder = createStep( export const cancelOrderExchangeWorkflowId = "cancel-exchange" /** - * This workflow cancels a confirmed exchange. + * This workflow cancels a confirmed exchange. It's used by the + * [Cancel Exchange Admin API Route](https://docs.medusajs.com/api/admin#exchanges_postexchangesidcancel). + * + * You can use this workflow within your customizations or your own custom workflows, allowing you to cancel an exchange + * for an order in your custom flow. + * + * @example + * const { result } = await cancelOrderExchangeWorkflow(container) + * .run({ + * input: { + * exchange_id: "exchange_123", + * } + * }) + * + * @summary + * + * Cancel an exchange for an order. */ export const cancelOrderExchangeWorkflow = createWorkflow( cancelOrderExchangeWorkflowId, diff --git a/packages/core/core-flows/src/order/workflows/exchange/confirm-exchange-request.ts b/packages/core/core-flows/src/order/workflows/exchange/confirm-exchange-request.ts index 78fecca7fc838..a4acf07065e07 100644 --- a/packages/core/core-flows/src/order/workflows/exchange/confirm-exchange-request.ts +++ b/packages/core/core-flows/src/order/workflows/exchange/confirm-exchange-request.ts @@ -42,13 +42,50 @@ import { } from "../../utils/order-validation" import { createOrUpdateOrderPaymentCollectionWorkflow } from "../create-or-update-order-payment-collection" -export type ConfirmExchangeRequestWorkflowInput = { - exchange_id: string - confirmed_by?: string +/** + * The data to validate that a requested exchange can be confirmed. + */ +export type ConfirmExchangeRequestValidationStepInput = { + /** + * The order's details. + */ + order: OrderDTO + /** + * The order exchange's details. + */ + orderExchange: OrderExchangeDTO + /** + * The order change's details. + */ + orderChange: OrderChangeDTO } /** * This step validates that a requested exchange can be confirmed. + * If the order or exchange is canceled, or the order change is not active, the step will throw an error. + * + * :::note + * + * You can retrieve an order, order exchange, and order change details using [Query](https://docs.medusajs.com/learn/fundamentals/module-links/query), + * or [useQueryGraphStep](https://docs.medusajs.com/resources/references/medusa-workflows/steps/useQueryGraphStep). + * + * ::: + * + * @example + * const data = confirmExchangeRequestValidationStep({ + * order: { + * id: "order_123", + * // other order details... + * }, + * orderChange: { + * id: "orch_123", + * // other order change details... + * }, + * orderExchange: { + * id: "exchange_123", + * // other order exchange details... + * }, + * }) */ export const confirmExchangeRequestValidationStep = createStep( "validate-confirm-exchange-request", @@ -56,11 +93,7 @@ export const confirmExchangeRequestValidationStep = createStep( order, orderChange, orderExchange, - }: { - order: OrderDTO - orderExchange: OrderExchangeDTO - orderChange: OrderChangeDTO - }) { + }: ConfirmExchangeRequestValidationStepInput) { throwIfIsCancelled(order, "Order") throwIfIsCancelled(orderExchange, "Exchange") throwIfOrderChangeIsNotActive({ orderChange }) @@ -215,9 +248,39 @@ function getUpdateReturnData({ returnId }: { returnId: string }) { }) } +/** + * The details to confirm an exchange request. + */ +export type ConfirmExchangeRequestWorkflowInput = { + /** + * The ID of the exchange to confirm. + */ + exchange_id: string + /** + * The ID of the user that's confirming the exchange. + */ + confirmed_by?: string +} + export const confirmExchangeRequestWorkflowId = "confirm-exchange-request" /** - * This workflow confirms an exchange request. + * This workflow confirms an exchange request. It's used by the + * [Confirm Exchange Admin API Route](https://docs.medusajs.com/api/admin#exchanges_postexchangesidrequest). + * + * You can use this workflow within your customizations or your own custom workflows, allowing you to confirm an exchange + * for an order in your custom flow. + * + * @example + * const { result } = await confirmExchangeRequestWorkflow(container) + * .run({ + * input: { + * exchange_id: "exchange_123", + * } + * }) + * + * @summary + * + * Confirm an exchange request. */ export const confirmExchangeRequestWorkflow = createWorkflow( confirmExchangeRequestWorkflowId, diff --git a/packages/core/core-flows/src/order/workflows/exchange/create-exchange-shipping-method.ts b/packages/core/core-flows/src/order/workflows/exchange/create-exchange-shipping-method.ts index e93a267f1fad6..62bfc3dd18689 100644 --- a/packages/core/core-flows/src/order/workflows/exchange/create-exchange-shipping-method.ts +++ b/packages/core/core-flows/src/order/workflows/exchange/create-exchange-shipping-method.ts @@ -24,7 +24,49 @@ import { createOrderChangeActionsWorkflow } from "../create-order-change-actions import { updateOrderTaxLinesWorkflow } from "../update-tax-lines" /** - * This step validates that a shipping method can be created for an exchange. + * The data to validate that a shipping method can be created for an exchange. + */ +export type CreateExchangeShippingMethodValidationStepInput = { + /** + * The order's details. + */ + order: OrderDTO + /** + * The order exchange's details. + */ + orderExchange: OrderExchangeDTO + /** + * The order change's details. + */ + orderChange: OrderChangeDTO +} + +/** + * This step validates that an inbound or outbound shipping method can be created for an exchange. + * If the order or exchange is canceled, or the order change is not active, the step will throw an error. + * + * :::note + * + * You can retrieve an order, order exchange, and order change details using [Query](https://docs.medusajs.com/learn/fundamentals/module-links/query), + * or [useQueryGraphStep](https://docs.medusajs.com/resources/references/medusa-workflows/steps/useQueryGraphStep). + * + * ::: + * + * @example + * const data = createExchangeShippingMethodValidationStep({ + * order: { + * id: "order_123", + * // other order details... + * }, + * orderChange: { + * id: "orch_123", + * // other order change details... + * }, + * orderExchange: { + * id: "exchange_123", + * // other order exchange details... + * }, + * }) */ export const createExchangeShippingMethodValidationStep = createStep( "validate-create-exchange-shipping-method", @@ -32,30 +74,81 @@ export const createExchangeShippingMethodValidationStep = createStep( order, orderChange, orderExchange, - }: { - order: OrderDTO - orderExchange: OrderExchangeDTO - orderChange: OrderChangeDTO - }) { + }: CreateExchangeShippingMethodValidationStepInput) { throwIfIsCancelled(order, "Order") throwIfIsCancelled(orderExchange, "Exchange") throwIfOrderChangeIsNotActive({ orderChange }) } ) +/** + * The details to create the shipping method for the exchange. + */ +export type CreateExchangeShippingMethodWorkflowInput = { + /** + * The ID of the return associated with the exchange. + * If set, an inbound shipping method will be created for the return. + * If not set, an outbound shipping method will be created for the exchange. + */ + return_id?: string + /** + * The ID of the exchange to create the shipping method for. + */ + exchange_id?: string + /** + * The ID of the shipping option to create the shipping method from. + */ + shipping_option_id: string + /** + * The custom amount to charge for the shipping method. + * If not set, the shipping option's amount is used. + */ + custom_amount?: BigNumberInput | null +} + export const createExchangeShippingMethodWorkflowId = "create-exchange-shipping-method" /** - * This workflow creates a shipping method for an exchange. + * This workflow creates an inbound (return) or outbound (delivery of new items) shipping method for an exchange. + * It's used by the [Add Inbound Shipping Admin API Route](https://docs.medusajs.com/api/admin#exchanges_postexchangesidinboundshippingmethod) + * and the [Add Outbound Shipping Admin API Route](https://docs.medusajs.com/api/admin#exchanges_postexchangesidoutboundshippingmethod). + * + * You can use this workflow within your customizations or your own custom workflows, allowing you to create a shipping method + * for an exchange in your custom flow. + * + * @example + * To create an outbound shipping method for the exchange: + * + * ```ts + * const { result } = await createExchangeShippingMethodWorkflow(container) + * .run({ + * input: { + * exchange_id: "exchange_123", + * shipping_option_id: "so_123" + * } + * }) + * ``` + * + * To create an inbound shipping method, pass the ID of the return associated with the exchange: + * + * ```ts + * const { result } = await createExchangeShippingMethodWorkflow(container) + * .run({ + * input: { + * exchange_id: "exchange_123", + * return_id: "return_123", + * shipping_option_id: "so_123" + * } + * }) + * ``` + * + * @summary + * + * Create an inbound or outbound shipping method for an exchange. */ export const createExchangeShippingMethodWorkflow = createWorkflow( createExchangeShippingMethodWorkflowId, - function (input: { - return_id?: string - exchange_id?: string - shipping_option_id: string - custom_amount?: BigNumberInput | null - }): WorkflowResponse { + function (input: CreateExchangeShippingMethodWorkflowInput): WorkflowResponse { const orderExchange: OrderExchangeDTO = useRemoteQueryStep({ entry_point: "order_exchange", fields: ["id", "status", "order_id", "canceled_at"], diff --git a/packages/core/core-flows/src/order/workflows/exchange/exchange-add-new-item.ts b/packages/core/core-flows/src/order/workflows/exchange/exchange-add-new-item.ts index da7c9a1a8e5a9..1bd3518e47a5c 100644 --- a/packages/core/core-flows/src/order/workflows/exchange/exchange-add-new-item.ts +++ b/packages/core/core-flows/src/order/workflows/exchange/exchange-add-new-item.ts @@ -24,7 +24,49 @@ import { createOrderChangeActionsWorkflow } from "../create-order-change-actions import { updateOrderTaxLinesWorkflow } from "../update-tax-lines" /** - * This step validates that new items can be added to an exchange. + * The data to validate that new or outbound items can be added to an exchange. + */ +export type ExchangeAddNewItemValidationStepInput = { + /** + * The order's details. + */ + order: OrderDTO + /** + * The order exchange's details. + */ + orderExchange: OrderExchangeDTO + /** + * The order change's details. + */ + orderChange: OrderChangeDTO +} + +/** + * This step validates that new or outbound items can be added to an exchange. + * If the order or exchange is canceled, or the order change is not active, the step will throw an error. + * + * :::note + * + * You can retrieve an order, order exchange, and order change details using [Query](https://docs.medusajs.com/learn/fundamentals/module-links/query), + * or [useQueryGraphStep](https://docs.medusajs.com/resources/references/medusa-workflows/steps/useQueryGraphStep). + * + * ::: + * + * @example + * const data = exchangeAddNewItemValidationStep({ + * order: { + * id: "order_123", + * // other order details... + * }, + * orderChange: { + * id: "orch_123", + * // other order change details... + * }, + * orderExchange: { + * id: "exchange_123", + * // other order exchange details... + * }, + * }) */ export const exchangeAddNewItemValidationStep = createStep( "exchange-add-new-item-validation", @@ -32,11 +74,7 @@ export const exchangeAddNewItemValidationStep = createStep( order, orderChange, orderExchange, - }: { - order: OrderDTO - orderExchange: OrderExchangeDTO - orderChange: OrderChangeDTO - }) { + }: ExchangeAddNewItemValidationStepInput) { throwIfIsCancelled(order, "Order") throwIfIsCancelled(orderExchange, "Exchange") throwIfOrderChangeIsNotActive({ orderChange }) @@ -45,7 +83,29 @@ export const exchangeAddNewItemValidationStep = createStep( export const orderExchangeAddNewItemWorkflowId = "exchange-add-new-item" /** - * This workflow adds new items to an exchange. + * This workflow adds new or outbound items to an exchange. It's used by the + * [Add Outbound Items Admin API Route](https://docs.medusajs.com/api/admin#exchanges_postexchangesidoutbounditems). + * + * You can use this workflow within your customizations or your own custom workflows, allowing you to add new or outbound items + * to an exchange in your custom flow. + * + * @example + * const { result } = await orderExchangeAddNewItemWorkflow(container) + * .run({ + * input: { + * exchange_id: "exchange_123", + * items: [ + * { + * variant_id: "variant_123", + * quantity: 1, + * } + * ] + * } + * }) + * + * @summary + * + * Add new or outbound items to an exchange. */ export const orderExchangeAddNewItemWorkflow = createWorkflow( orderExchangeAddNewItemWorkflowId, diff --git a/packages/core/core-flows/src/order/workflows/exchange/exchange-request-item-return.ts b/packages/core/core-flows/src/order/workflows/exchange/exchange-request-item-return.ts index a8a9d83da3f4a..25194885f62fc 100644 --- a/packages/core/core-flows/src/order/workflows/exchange/exchange-request-item-return.ts +++ b/packages/core/core-flows/src/order/workflows/exchange/exchange-request-item-return.ts @@ -27,8 +27,69 @@ import { } from "../../utils/order-validation" import { createOrderChangeActionsWorkflow } from "../create-order-change-actions" +/** + * The data to validate that items can be returned as part of an exchange. + */ +export type ExchangeRequestItemReturnValidationStepInput = { + /** + * The order's details. + */ + order: OrderDTO + /** + * The order exchange's details. + */ + orderExchange: OrderExchangeDTO + /** + * The order change's details. + */ + orderChange: OrderChangeDTO + /** + * The order return's details. + */ + orderReturn: ReturnDTO + /** + * The items to be returned. + */ + items: OrderWorkflow.OrderExchangeRequestItemReturnWorkflowInput["items"] +} + /** * This step validates that items can be returned as part of an exchange. + * If the order, exchange, or return is canceled, the order change is not active, + * or the item doesn't exist in the order, the step will throw an error. + * + * :::note + * + * You can retrieve an order, order exchange, and order return details using [Query](https://docs.medusajs.com/learn/fundamentals/module-links/query), + * or [useQueryGraphStep](https://docs.medusajs.com/resources/references/medusa-workflows/steps/useQueryGraphStep). + * + * ::: + * + * @example + * const data = exchangeRequestItemReturnValidationStep({ + * order: { + * id: "order_123", + * // other order details... + * }, + * orderChange: { + * id: "orch_123", + * // other order change details... + * }, + * orderExchange: { + * id: "exchange_123", + * // other order exchange details... + * }, + * orderReturn: { + * id: "return_123", + * // other order return details... + * }, + * items: [ + * { + * id: "orli_123", + * quantity: 1, + * } + * ] + * }) */ export const exchangeRequestItemReturnValidationStep = createStep( "exchange-request-item-return-validation", @@ -38,13 +99,7 @@ export const exchangeRequestItemReturnValidationStep = createStep( orderReturn, orderExchange, items, - }: { - order: OrderDTO - orderReturn: ReturnDTO - orderExchange: OrderExchangeDTO - orderChange: OrderChangeDTO - items: OrderWorkflow.OrderExchangeRequestItemReturnWorkflowInput["items"] - }) { + }: ExchangeRequestItemReturnValidationStepInput) { throwIfIsCancelled(order, "Order") throwIfIsCancelled(orderExchange, "Exchange") throwIfIsCancelled(orderReturn, "Return") @@ -56,7 +111,30 @@ export const exchangeRequestItemReturnValidationStep = createStep( export const orderExchangeRequestItemReturnWorkflowId = "exchange-request-item-return" /** - * This workflow adds items to be retuned as part of the exchange. + * This workflow adds inbound items to be retuned as part of the exchange. It's used + * by the [Add Inbound Items Admin API Route](https://docs.medusajs.com/api/admin#exchanges_postexchangesidinbounditems). + * + * You can use this workflow within your customizations or your own custom workflows, allowing you to add inbound items + * to be returned as part of an exchange in your custom flow. + * + * @example + * const { result } = await orderExchangeRequestItemReturnWorkflow(container) + * .run({ + * input: { + * exchange_id: "exchange_123", + * return_id: "return_123", + * items: [ + * { + * id: "orli_123", + * quantity: 1, + * } + * ] + * } + * }) + * + * @summary + * + * Add inbound items to be returned as part of the exchange. */ export const orderExchangeRequestItemReturnWorkflow = createWorkflow( orderExchangeRequestItemReturnWorkflowId, diff --git a/packages/core/core-flows/src/order/workflows/exchange/remove-exchange-item-action.ts b/packages/core/core-flows/src/order/workflows/exchange/remove-exchange-item-action.ts index faf0c6fd17e74..33c8634c122c9 100644 --- a/packages/core/core-flows/src/order/workflows/exchange/remove-exchange-item-action.ts +++ b/packages/core/core-flows/src/order/workflows/exchange/remove-exchange-item-action.ts @@ -27,7 +27,59 @@ import { import { removeExchangeShippingMethodWorkflow } from "./remove-exchange-shipping-method" /** - * This step validates that a new item can be removed from an exchange. + * The data to validate that an outbound item can be removed from an exchange. + */ +export type RemoveExchangeItemActionValidationStepInput = { + /** + * The order's details. + */ + order: OrderDTO + /** + * The order exchange's details. + */ + orderExchange: OrderExchangeDTO + /** + * The order change's details. + */ + orderChange: OrderChangeDTO + /** + * The details of the item to remove. + */ + input: OrderWorkflow.DeleteOrderExchangeItemActionWorkflowInput +} + +/** + * This step validates that an outbound item can be removed from an exchange. + * If the order or exchange is canceled, the item is not found, + * or the order change is not active, the step will throw an error. + * + * :::note + * + * You can retrieve an order, order exchange, and order change details using [Query](https://docs.medusajs.com/learn/fundamentals/module-links/query), + * or [useQueryGraphStep](https://docs.medusajs.com/resources/references/medusa-workflows/steps/useQueryGraphStep). + * + * ::: + * + * @example + * const data = removeExchangeItemActionValidationStep({ + * order: { + * id: "order_123", + * // other order details... + * }, + * orderChange: { + * id: "orch_123", + * // other order change details... + * }, + * orderExchange: { + * id: "exchange_123", + * // other order exchange details... + * }, + * input: { + * exchange_id: "exchange_123", + * action_id: "orchact_123", + * } + * }) + * */ export const removeExchangeItemActionValidationStep = createStep( "remove-item-exchange-action-validation", @@ -36,12 +88,7 @@ export const removeExchangeItemActionValidationStep = createStep( orderChange, orderExchange, input, - }: { - order: OrderDTO - orderExchange: OrderExchangeDTO - orderChange: OrderChangeDTO - input: OrderWorkflow.DeleteOrderExchangeItemActionWorkflowInput - }) { + }: RemoveExchangeItemActionValidationStepInput) { throwIfIsCancelled(order, "Order") throwIfIsCancelled(orderExchange, "Exchange") throwIfOrderChangeIsNotActive({ orderChange }) @@ -62,7 +109,24 @@ export const removeExchangeItemActionValidationStep = createStep( export const removeItemExchangeActionWorkflowId = "remove-item-exchange-action" /** - * This workflow removes a new item in an exchange. + * This workflow removes an outbound or new item from an exchange. It's used by + * the [Remove Outbound Item API Route](https://docs.medusajs.com/api/admin#exchanges_deleteexchangesidoutbounditemsaction_id). + * + * You can use this workflow within your customizations or your own custom workflows, allowing you to remove an outbound or new item + * from an exchange in your custom flow. + * + * @example + * const { result } = await removeItemExchangeActionWorkflow(container) + * .run({ + * input: { + * exchange_id: "exchange_123", + * action_id: "orchact_123", + * } + * }) + * + * @summary + * + * Remove an outbound or new item from an exchange. */ export const removeItemExchangeActionWorkflow = createWorkflow( removeItemExchangeActionWorkflowId, diff --git a/packages/core/core-flows/src/order/workflows/exchange/remove-exchange-shipping-method.ts b/packages/core/core-flows/src/order/workflows/exchange/remove-exchange-shipping-method.ts index 475ea58fbe524..184e7d8923a0f 100644 --- a/packages/core/core-flows/src/order/workflows/exchange/remove-exchange-shipping-method.ts +++ b/packages/core/core-flows/src/order/workflows/exchange/remove-exchange-shipping-method.ts @@ -23,8 +23,51 @@ import { throwIfOrderChangeIsNotActive, } from "../../utils/order-validation" +/** + * The data to validate that a shipping method can be removed from an exchange. + */ +export type RemoveExchangeShippingMethodValidationStepInput = { + /** + * The order exchange's details. + */ + orderExchange: OrderExchangeDTO + /** + * The order change's details. + */ + orderChange: OrderChangeDTO + /** + * The details of the action. + */ + input: Pick +} + /** * This step validates that a shipping method can be removed from an exchange. + * If the exchange is canceled, the order change is not active, the shipping method + * doesn't exist, or the action isn't adding a shipping method, the step will throw an error. + * + * :::note + * + * You can retrieve an order exchange and order change details using [Query](https://docs.medusajs.com/learn/fundamentals/module-links/query), + * or [useQueryGraphStep](https://docs.medusajs.com/resources/references/medusa-workflows/steps/useQueryGraphStep). + * + * ::: + * + * @example + * const data = removeExchangeShippingMethodValidationStep({ + * orderChange: { + * id: "orch_123", + * // other order change details... + * }, + * orderExchange: { + * id: "exchange_123", + * // other order exchange details... + * }, + * input: { + * exchange_id: "exchange_123", + * action_id: "orchact_123", + * } + * }) */ export const removeExchangeShippingMethodValidationStep = createStep( "validate-remove-exchange-shipping-method", @@ -32,11 +75,7 @@ export const removeExchangeShippingMethodValidationStep = createStep( orderChange, orderExchange, input, - }: { - input: { exchange_id: string; action_id: string } - orderExchange: OrderExchangeDTO - orderChange: OrderChangeDTO - }) { + }: RemoveExchangeShippingMethodValidationStepInput) { throwIfIsCancelled(orderExchange, "Exchange") throwIfOrderChangeIsNotActive({ orderChange }) @@ -59,7 +98,25 @@ export const removeExchangeShippingMethodValidationStep = createStep( export const removeExchangeShippingMethodWorkflowId = "remove-exchange-shipping-method" /** - * This workflow removes a shipping method of an exchange. + * This workflow removes an inbound or outbound shipping method of an exchange. It's used by the + * [Remove Inbound Shipping Admin API Route](https://docs.medusajs.com/api/admin#exchanges_deleteexchangesidinboundshippingmethodaction_id) or + * the [Remove Outbound Shipping Admin API Route](https://docs.medusajs.com/api/admin#exchanges_deleteexchangesidoutboundshippingmethodaction_id). + * + * You can use this workflow within your customizations or your own custom workflows, allowing you to remove an inbound or outbound shipping method + * from an exchange in your custom flow. + * + * @example + * const { result } = await removeExchangeShippingMethodWorkflow(container) + * .run({ + * input: { + * exchange_id: "exchange_123", + * action_id: "orchact_123", + * } + * }) + * + * @summary + * + * Remove an inbound or outbound shipping method from an exchange. */ export const removeExchangeShippingMethodWorkflow = createWorkflow( removeExchangeShippingMethodWorkflowId, diff --git a/packages/core/core-flows/src/order/workflows/exchange/update-exchange-add-item.ts b/packages/core/core-flows/src/order/workflows/exchange/update-exchange-add-item.ts index d95d405113626..8b5b2c785ba87 100644 --- a/packages/core/core-flows/src/order/workflows/exchange/update-exchange-add-item.ts +++ b/packages/core/core-flows/src/order/workflows/exchange/update-exchange-add-item.ts @@ -25,7 +25,61 @@ import { } from "../../utils/order-validation" /** - * This step validates that a new item can be removed from an exchange. + * The data to validate that an outbound or new item in an exchange can be updated. + */ +export type UpdateExchangeAddItemValidationStepInput = { + /** + * The order's details. + */ + order: OrderDTO + /** + * The order exchange's details. + */ + orderExchange: OrderExchangeDTO + /** + * The order change's details. + */ + orderChange: OrderChangeDTO + /** + * The details of the item update. + */ + input: OrderWorkflow.UpdateExchangeAddNewItemWorkflowInput +} + +/** + * This step validates that an outbound or new item can be removed from an exchange. + * If the order or exchange is canceled, the item is not found in the exchange, + * or the order change is not active, the step will throw an error. + * + * :::note + * + * You can retrieve an order, order exchange, and order change details using [Query](https://docs.medusajs.com/learn/fundamentals/module-links/query), + * or [useQueryGraphStep](https://docs.medusajs.com/resources/references/medusa-workflows/steps/useQueryGraphStep). + * + * ::: + * + * @example + * const data = updateExchangeAddItemValidationStep({ + * order: { + * id: "order_123", + * // other order details... + * }, + * orderChange: { + * id: "orch_123", + * // other order change details... + * }, + * orderExchange: { + * id: "exchange_123", + * // other order exchange details... + * }, + * input: { + * exchange_id: "exchange_123", + * action_id: "orchact_123", + * data: { + * quantity: 1 + * } + * } + * }) */ export const updateExchangeAddItemValidationStep = createStep( "update-exchange-add-item-validation", @@ -35,12 +89,7 @@ export const updateExchangeAddItemValidationStep = createStep( orderChange, orderExchange, input, - }: { - order: OrderDTO - orderExchange: OrderExchangeDTO - orderChange: OrderChangeDTO - input: OrderWorkflow.UpdateExchangeAddNewItemWorkflowInput - }, + }: UpdateExchangeAddItemValidationStepInput, context ) { throwIfIsCancelled(order, "Order") @@ -63,7 +112,27 @@ export const updateExchangeAddItemValidationStep = createStep( export const updateExchangeAddItemWorkflowId = "update-exchange-add-item" /** - * This workflow updates a new item in the exchange. + * This workflow updates an outbound or new item in the exchange. It's used by the + * [Update Outbound Item Admin API Route](https://docs.medusajs.com/api/admin#exchanges_postexchangesidoutbounditemsaction_id). + * + * You can use this workflow within your customizations or your own custom workflows, allowing you to update an outbound or new item + * in an exchange in your custom flow. + * + * @example + * const { result } = await updateExchangeAddItemWorkflow(container) + * .run({ + * input: { + * exchange_id: "exchange_123", + * action_id: "orchact_123", + * data: { + * quantity: 1 + * } + * } + * }) + * + * @summary + * + * Update an outbound or new item in an exchange. */ export const updateExchangeAddItemWorkflow = createWorkflow( updateExchangeAddItemWorkflowId, diff --git a/packages/core/core-flows/src/order/workflows/exchange/update-exchange-shipping-method.ts b/packages/core/core-flows/src/order/workflows/exchange/update-exchange-shipping-method.ts index 3adaa5e60cb51..e1117790812be 100644 --- a/packages/core/core-flows/src/order/workflows/exchange/update-exchange-shipping-method.ts +++ b/packages/core/core-flows/src/order/workflows/exchange/update-exchange-shipping-method.ts @@ -27,8 +27,55 @@ import { } from "../../utils/order-validation" import { prepareShippingMethodUpdate } from "../../utils/prepare-shipping-method" +/** + * The data to validate that an exchange's shipping method can be updated. + */ +export type UpdateExchangeShippingMethodValidationStepInput = { + /** + * The order exchange's details. + */ + orderExchange: OrderExchangeDTO + /** + * The order change's details. + */ + orderChange: OrderChangeDTO + /** + * The details of the shipping method update. + */ + input: Pick +} + /** * This step validates that an exchange's shipping method can be updated. + * If the exchange is canceled, the order change is not active, the shipping method + * doesn't exist in the exchange, or the action isn't adding a shipping method, + * the step will throw an error. + * + * :::note + * + * You can retrieve an order exchange and order change details using [Query](https://docs.medusajs.com/learn/fundamentals/module-links/query), + * or [useQueryGraphStep](https://docs.medusajs.com/resources/references/medusa-workflows/steps/useQueryGraphStep). + * + * ::: + * + * @example + * const data = updateExchangeShippingMethodValidationStep({ + * orderChange: { + * id: "orch_123", + * // other order change details... + * }, + * orderExchange: { + * id: "exchange_123", + * // other order exchange details... + * }, + * input: { + * exchange_id: "exchange_123", + * action_id: "orchact_123", + * data: { + * custom_amount: 10, + * } + * } + * }) */ export const updateExchangeShippingMethodValidationStep = createStep( "validate-update-exchange-shipping-method", @@ -36,11 +83,7 @@ export const updateExchangeShippingMethodValidationStep = createStep( orderChange, orderExchange, input, - }: { - input: { exchange_id: string; action_id: string } - orderExchange: OrderExchangeDTO - orderChange: OrderChangeDTO - }) { + }: UpdateExchangeShippingMethodValidationStepInput) { throwIfIsCancelled(orderExchange, "Exchange") throwIfOrderChangeIsNotActive({ orderChange }) @@ -63,7 +106,28 @@ export const updateExchangeShippingMethodValidationStep = createStep( export const updateExchangeShippingMethodWorkflowId = "update-exchange-shipping-method" /** - * This workflow updates an exchange's shipping method. + * This workflow updates an exchange's inbound or outbound shipping method. It's used by the + * [Update Inbound Shipping Admin API Route](https://docs.medusajs.com/api/admin#exchanges_postexchangesidinboundshippingmethodaction_id) + * or the [Outbound Inbound Shipping Admin API Route](https://docs.medusajs.com/api/admin#exchanges_postexchangesidoutboundshippingmethodaction_id). + * + * You can use this workflow within your customizations or your own custom workflows, allowing you to update an exchange's + * inbound or outbound shipping method in your custom flow. + * + * @example + * const { result } = await updateExchangeShippingMethodWorkflow(container) + * .run({ + * input: { + * exchange_id: "exchange_123", + * action_id: "orchact_123", + * data: { + * custom_amount: 10, + * } + * } + * }) + * + * @summary + * + * Update an exchange's inbound or outbound shipping method. */ export const updateExchangeShippingMethodWorkflow = createWorkflow( updateExchangeShippingMethodWorkflowId, diff --git a/packages/core/core-flows/src/order/workflows/get-order-detail.ts b/packages/core/core-flows/src/order/workflows/get-order-detail.ts index 1833fac19b340..7c272e2fd53bd 100644 --- a/packages/core/core-flows/src/order/workflows/get-order-detail.ts +++ b/packages/core/core-flows/src/order/workflows/get-order-detail.ts @@ -12,19 +12,66 @@ import { getLastPaymentStatus, } from "../utils/aggregate-status" +/** + * The data to retrieve an order's details. + */ +export type GetOrderDetailWorkflowInput = { + /** + * Additional filters to apply on the retrieved order. + */ + filters?: { + /** + * Whether to retrieve a draft order. + */ + is_draft_order?: boolean + /** + * The ID of the customer that the order belongs to. + */ + customer_id?: string + } + /** + * The fields and relations to retrieve in the order. These fields + * are passed to [Query](https://docs.medusajs.com/learn/fundamentals/module-links/query), + * so you can pass names of custom models linked to the order. + */ + fields: string[] + /** + * The ID of the order to retrieve. + */ + order_id: string + /** + * The version of the order to retrieve. If not provided, the latest version + * of the order will be retrieved. + */ + version?: number +} + export const getOrderDetailWorkflowId = "get-order-detail" /** - * This workflow retrieves an order's details. + * This workflow retrieves an order's details. It's used by many API routes, including + * [Get an Order Admin API Route](https://docs.medusajs.com/api/admin#orders_getordersid), and + * [Get an Order Store API Route](https://docs.medusajs.com/api/store#orders_getordersid). + * + * You can use this workflow within your customizations or your own custom workflows, allowing you to retrieve an + * order's details in your custom flows. + * + * @example + * const { result } = await getOrderDetailWorkflow(container) + * .run({ + * input: { + * order_id: "order_123", + * fields: ["id", "status", "items"] + * } + * }) + * + * @summary + * + * Retrieve an order's details. */ export const getOrderDetailWorkflow = createWorkflow( getOrderDetailWorkflowId, ( - input: WorkflowData<{ - filters?: { is_draft_order?: boolean; customer_id?: string } - fields: string[] - order_id: string - version?: number - }> + input: WorkflowData ): WorkflowResponse => { const fields = transform(input, ({ fields }) => { return deduplicate([ diff --git a/packages/core/core-flows/src/order/workflows/get-orders-list.ts b/packages/core/core-flows/src/order/workflows/get-orders-list.ts index b77dcffa1e31a..e03e11fcce9c6 100644 --- a/packages/core/core-flows/src/order/workflows/get-orders-list.ts +++ b/packages/core/core-flows/src/order/workflows/get-orders-list.ts @@ -12,24 +12,109 @@ import { getLastPaymentStatus, } from "../utils/aggregate-status" +/** + * The retrieved list of orders. If you passed pagination configurations in the + * input, the response will return an object that includes the list of + * orders and their pagination details. Otherwise, only the list of orders are returned. + */ export type GetOrdersListWorkflowOutput = | OrderDTO[] | { + /** + * The list of orders. + */ rows: OrderDTO[] - metadata: any + /** + * Pagination details. + */ + metadata: { + /** + * The total number of orders. + */ + count: number + /** + * The number of items skipped before retrieving the returned orders. + */ + skip: number + /** + * The number of items to retrieve. + */ + take: number + } } +export type GetOrdersListWorkflowInput = { + /** + * The fields and relations to retrieve in the order. These fields + * are passed to [Query](https://docs.medusajs.com/learn/fundamentals/module-links/query), + * so you can pass names of custom models linked to the order. + */ + fields: string[] + /** + * Filters and pagination configurations to apply on the retrieved orders. + */ + variables?: Record & { + /** + * The number of items to skip before retrieving the orders. + */ + skip?: number + /** + * The number of items to retrieve. + */ + take?: number + /** + * Fields to sort the orders by. The key is the field name, and the value is either + * `ASC` for ascending order or `DESC` for descending order. + */ + order?: Record + } +} + export const getOrdersListWorkflowId = "get-orders-list" /** - * This workflow retrieves a list of orders. + * This workflow retrieves a list of orders. It's used by the + * [List Orders Admin API Route](https://docs.medusajs.com/api/admin#orders_getorders), and the + * [List Orders Store API Route](https://docs.medusajs.com/api/store#orders_getorders). + * + * You can use this workflow within your customizations or your own custom workflows, allowing you to retrieve a list of + * orders in your custom flows. For example, you can retrieve the list of orders to export them + * to a third-party system. + * + * @example + * To retrieve the list of orders: + * + * ```ts + * const { result } = await getOrdersListWorkflow(container) + * .run({ + * input: { + * fields: ["id", "status", "items"], + * } + * }) + * ``` + * + * To retrieve the list of orders with pagination: + * + * ```ts + * const { result } = await getOrdersListWorkflow(container) + * .run({ + * input: { + * fields: ["id", "status", "items"], + * variables: { + * skip: 0, + * take: 15, + * } + * } + * }) + * ``` + * + * @summary + * + * Retrieve a list of orders. */ export const getOrdersListWorkflow = createWorkflow( getOrdersListWorkflowId, ( - input: WorkflowData<{ - fields: string[] - variables?: Record - }> + input: WorkflowData ): WorkflowResponse => { const fields = transform(input, ({ fields }) => { return deduplicate([ diff --git a/packages/core/core-flows/src/order/workflows/index.ts b/packages/core/core-flows/src/order/workflows/index.ts index 5127968932b56..d919bf27ee0bc 100644 --- a/packages/core/core-flows/src/order/workflows/index.ts +++ b/packages/core/core-flows/src/order/workflows/index.ts @@ -83,3 +83,4 @@ export * from "./transfer/accept-order-transfer" export * from "./transfer/cancel-order-transfer" export * from "./transfer/decline-order-transfer" export * from "./update-order" +export * from "./create-or-update-order-payment-collection" \ No newline at end of file diff --git a/packages/core/core-flows/src/order/workflows/mark-order-fulfillment-as-delivered.ts b/packages/core/core-flows/src/order/workflows/mark-order-fulfillment-as-delivered.ts index 6fa9d56328378..887984bf67f11 100644 --- a/packages/core/core-flows/src/order/workflows/mark-order-fulfillment-as-delivered.ts +++ b/packages/core/core-flows/src/order/workflows/mark-order-fulfillment-as-delivered.ts @@ -20,10 +20,56 @@ import { throwIfOrderIsCancelled, } from "../utils/order-validation" +/** + * The data to validate the order fulfillment deliverability. + */ +export type OrderFulfillmentDeliverabilityValidationStepInput = { + /** + * The order to validate the fulfillment deliverability for. + */ + order: OrderDTO & { + /** + * The fulfillments in the order. + */ + fulfillments: FulfillmentDTO[] + } + /** + * The fulfillment to validate the deliverability for. + */ + fulfillment: FulfillmentDTO +} + export const orderFulfillmentDeliverablilityValidationStepId = "order-fulfillment-deliverability-validation" /** - * This step validates that order & fulfillment are valid + * This step validates that the order fulfillment can be delivered. If the order is cancelled, + * the items to mark as delivered don't exist in the order, or the fulfillment doesn't exist in the order, + * the step will throw an error. + * + * :::note + * + * You can retrieve an order and fulfillment's details using [Query](https://docs.medusajs.com/learn/fundamentals/module-links/query), + * or [useQueryGraphStep](https://docs.medusajs.com/resources/references/medusa-workflows/steps/useQueryGraphStep). + * + * ::: + * + * @example + * const data = orderFulfillmentDeliverablilityValidationStep({ + * order: { + * id: "order_123", + * fulfillments: [ + * { + * id: "ful_123", + * // other fulfillment details... + * } + * ] + * // other order details... + * }, + * fulfillment: { + * id: "ful_123", + * // other fulfillment details... + * } + * }) */ export const orderFulfillmentDeliverablilityValidationStep = createStep( orderFulfillmentDeliverablilityValidationStepId, @@ -80,14 +126,45 @@ function prepareRegisterDeliveryData({ } } +/** + * The details to mark a fulfillment in an order as delivered. + */ +export type MarkOrderFulfillmentAsDeliveredWorkflowInput = { + /** + * The ID of the order to mark the fulfillment as delivered in. + */ + orderId: string + /** + * The ID of the fulfillment to mark as delivered. + */ + fulfillmentId: string +} + export const markOrderFulfillmentAsDeliveredWorkflowId = "mark-order-fulfillment-as-delivered-workflow" /** - * This workflow marks a fulfillment in an order as delivered. + * This workflow marks a fulfillment in an order as delivered. It's used by the + * [Mark Fulfillment as Delivered Admin API Route](https://docs.medusajs.com/api/admin#orders_postordersidfulfillmentsfulfillment_idmarkasdelivered). + * + * You can use this workflow within your customizations or your own custom workflows, allowing you to wrap custom logic around + * marking a fulfillment as delivered. + * + * @example + * const { result } = await markOrderFulfillmentAsDeliveredWorkflow(container) + * .run({ + * input: { + * orderId: "order_123", + * fulfillmentId: "ful_123", + * } + * }) + * + * @summary + * + * Mark a fulfillment in an order as delivered. */ export const markOrderFulfillmentAsDeliveredWorkflow = createWorkflow( markOrderFulfillmentAsDeliveredWorkflowId, - (input: WorkflowData<{ orderId: string; fulfillmentId: string }>) => { + (input: WorkflowData) => { const { fulfillmentId, orderId } = input const fulfillment = useRemoteQueryStep({ entry_point: "fulfillment", diff --git a/packages/core/core-flows/src/order/workflows/mark-payment-collection-as-paid.ts b/packages/core/core-flows/src/order/workflows/mark-payment-collection-as-paid.ts index 0e264c19ce408..ef057abace59c 100644 --- a/packages/core/core-flows/src/order/workflows/mark-payment-collection-as-paid.ts +++ b/packages/core/core-flows/src/order/workflows/mark-payment-collection-as-paid.ts @@ -14,11 +14,37 @@ import { import { createPaymentSessionsWorkflow } from "../../payment-collection" /** - * This step validates that the payment collection is not_paid + * The details of the payment collection to validate. + */ +export type ThrowUnlessPaymentCollectionNotePaidInput = { + /** + * The payment collection to validate. + */ + paymentCollection: PaymentCollectionDTO +} + +/** + * This step validates that the payment collection is not paid. If not valid, + * the step will throw an error. + * + * :::note + * + * You can retrieve a payment collection's details using [Query](https://docs.medusajs.com/learn/fundamentals/module-links/query), + * or [useQueryGraphStep](https://docs.medusajs.com/resources/references/medusa-workflows/steps/useQueryGraphStep). + * + * ::: + * + * @example + * const data = throwUnlessPaymentCollectionNotPaid({ + * paymentCollection: { + * id: "paycol_123", + * // other payment details... + * } + * }) */ export const throwUnlessPaymentCollectionNotPaid = createStep( "validate-existing-payment-collection", - ({ paymentCollection }: { paymentCollection: PaymentCollectionDTO }) => { + ({ paymentCollection }: ThrowUnlessPaymentCollectionNotePaidInput) => { if (paymentCollection.status !== "not_paid") { throw new MedusaError( MedusaError.Types.NOT_ALLOWED, @@ -28,19 +54,50 @@ export const throwUnlessPaymentCollectionNotPaid = createStep( } ) +/** + * The data to mark a payment collection as paid. + */ +export type MarkPaymentCollectionAsPaidInput = { + /** + * The ID of the payment collection to mark as paid. + */ + payment_collection_id: string + /** + * The ID of the order that the payment collection belongs to. + */ + order_id: string + /** + * The ID of the user marking the payment collection as completed. + */ + captured_by?: string +} + const systemPaymentProviderId = "pp_system_default" export const markPaymentCollectionAsPaidId = "mark-payment-collection-as-paid" /** - * This workflow marks a payment collection for an order as paid. + * This workflow marks a payment collection for an order as paid. It's used by the + * [Mark Payment Collection as Paid Admin API Route](https://docs.medusajs.com/api/admin#payment-collections_postpaymentcollectionsidmarkaspaid). + * + * You can use this workflow within your customizations or your own custom workflows, allowing you to wrap custom logic around + * marking a payment collection for an order as paid. + * + * @example + * const { result } = await markPaymentCollectionAsPaid(container) + * .run({ + * input: { + * order_id: "order_123", + * payment_collection_id: "paycol_123", + * } + * }) + * + * @summary + * + * Mark a payment collection for an order as paid. */ export const markPaymentCollectionAsPaid = createWorkflow( markPaymentCollectionAsPaidId, ( - input: WorkflowData<{ - payment_collection_id: string - order_id: string - captured_by?: string - }> + input: WorkflowData ) => { const paymentCollection = useRemoteQueryStep({ entry_point: "payment_collection", diff --git a/packages/core/core-flows/src/order/workflows/order-edit/begin-order-edit.ts b/packages/core/core-flows/src/order/workflows/order-edit/begin-order-edit.ts index d9501fa80f3c5..31331b2c949d8 100644 --- a/packages/core/core-flows/src/order/workflows/order-edit/begin-order-edit.ts +++ b/packages/core/core-flows/src/order/workflows/order-edit/begin-order-edit.ts @@ -14,19 +14,64 @@ import { useRemoteQueryStep } from "../../../common" import { createOrderChangeStep } from "../../steps/create-order-change" import { throwIfOrderIsCancelled } from "../../utils/order-validation" +/** + * The data to validate that an order-edit can be requested for an order. + */ +export type BeginOrderEditValidationStepInput = { + /** + * The order's details. + */ + order: OrderDTO +} + /** * This step validates that an order-edit can be requested for an order. + * If the order is canceled, the step will throw an error. + * + * :::note + * + * You can retrieve an order's details using [Query](https://docs.medusajs.com/learn/fundamentals/module-links/query), + * or [useQueryGraphStep](https://docs.medusajs.com/resources/references/medusa-workflows/steps/useQueryGraphStep). + * + * ::: + * + * @example + * const data = beginOrderEditValidationStep({ + * order: { + * id: "order_123", + * // other order details... + * } + * }) */ export const beginOrderEditValidationStep = createStep( "begin-order-edit-validation", - async function ({ order }: { order: OrderDTO }) { + async function ({ order }: BeginOrderEditValidationStepInput) { throwIfOrderIsCancelled({ order }) } ) export const beginOrderEditOrderWorkflowId = "begin-order-edit-order" /** - * This workflow requests an order order-edit. + * This workflow creates an order edit request. It' used by the + * [Create Order Edit Admin API Route](https://docs.medusajs.com/api/admin#order-edits_postorderedits). + * + * To request the order edit, use the {@link requestOrderEditRequestWorkflow}. The order edit is then only applied after the + * order edit is confirmed using the {@link confirmOrderEditRequestWorkflow}. + * + * You can use this workflow within your customizations or your own custom workflows, allowing you to create an order edit + * for an order in your custom flows. + * + * @example + * const { result } = await beginOrderEditOrderWorkflow(container) + * .run({ + * input: { + * order_id: "order_123", + * } + * }) + * + * @summary + * + * Create an order edit request. */ export const beginOrderEditOrderWorkflow = createWorkflow( beginOrderEditOrderWorkflowId, diff --git a/packages/core/core-flows/src/order/workflows/order-edit/cancel-begin-order-edit.ts b/packages/core/core-flows/src/order/workflows/order-edit/cancel-begin-order-edit.ts index 85805e26e0125..dcd00f76f9626 100644 --- a/packages/core/core-flows/src/order/workflows/order-edit/cancel-begin-order-edit.ts +++ b/packages/core/core-flows/src/order/workflows/order-edit/cancel-begin-order-edit.ts @@ -14,30 +14,83 @@ import { throwIfOrderChangeIsNotActive, } from "../../utils/order-validation" -export type CancelBeginOrderEditWorkflowInput = { - order_id: string +/** + * The data to validate that a requested order edit can be canceled. + */ +export type CancelBeginOrderEditValidationStepInput = { + /** + * The order's details. + */ + order: OrderDTO + /** + * The order change's details. + */ + orderChange: OrderChangeDTO } /** * This step validates that a requested order edit can be canceled. + * If the order is canceled or the order change is not active, the step will throw an error. + * + * :::note + * + * You can retrieve an order and order change details using [Query](https://docs.medusajs.com/learn/fundamentals/module-links/query), + * or [useQueryGraphStep](https://docs.medusajs.com/resources/references/medusa-workflows/steps/useQueryGraphStep). + * + * ::: + * + * @example + * const data = cancelBeginOrderEditValidationStep({ + * order: { + * id: "order_123", + * // other order details... + * }, + * orderChange: { + * id: "orch_123", + * // other order change details... + * } + * }) */ export const cancelBeginOrderEditValidationStep = createStep( "validate-cancel-begin-order-edit", async function ({ order, orderChange, - }: { - order: OrderDTO - orderChange: OrderChangeDTO - }) { + }: CancelBeginOrderEditValidationStepInput) { throwIfIsCancelled(order, "Order") throwIfOrderChangeIsNotActive({ orderChange }) } ) +/** + * The data to cancel a requested order edit. + */ +export type CancelBeginOrderEditWorkflowInput = { + /** + * The ID of the order to cancel the edit for. + */ + order_id: string +} + export const cancelBeginOrderEditWorkflowId = "cancel-begin-order-edit" /** - * This workflow cancels a requested order edit. + * This workflow cancels a requested edit for an order. It's used by the + * [Cancel Order Edit Admin API Route](https://docs.medusajs.com/api/admin#order-edits_deleteordereditsid). + * + * You can use this workflow within your customizations or your own custom workflows, allowing you to cancel an order edit + * in your custom flow. + * + * @example + * const { result } = await cancelBeginOrderEditWorkflow(container) + * .run({ + * input: { + * order_id: "order_123", + * } + * }) + * + * @summary + * + * Cancel a requested order edit. */ export const cancelBeginOrderEditWorkflow = createWorkflow( cancelBeginOrderEditWorkflowId, diff --git a/packages/core/core-flows/src/order/workflows/order-edit/confirm-order-edit-request.ts b/packages/core/core-flows/src/order/workflows/order-edit/confirm-order-edit-request.ts index 20ac78cc7eb08..422ab800570fc 100644 --- a/packages/core/core-flows/src/order/workflows/order-edit/confirm-order-edit-request.ts +++ b/packages/core/core-flows/src/order/workflows/order-edit/confirm-order-edit-request.ts @@ -27,31 +27,87 @@ import { } from "../../utils/order-validation" import { createOrUpdateOrderPaymentCollectionWorkflow } from "../create-or-update-order-payment-collection" -export type ConfirmOrderEditRequestWorkflowInput = { - order_id: string - confirmed_by?: string +/** + * The data to validate that a requested order edit can be confirmed. + */ +export type ConfirmOrderEditRequestValidationStepInput = { + /** + * The order's details. + */ + order: OrderDTO + /** + * The order change's details. + */ + orderChange: OrderChangeDTO } /** * This step validates that a requested order edit can be confirmed. + * If the order is canceled or the order change is not active, the step will throw an error. + * + * :::note + * + * You can retrieve an order and order change details using [Query](https://docs.medusajs.com/learn/fundamentals/module-links/query), + * or [useQueryGraphStep](https://docs.medusajs.com/resources/references/medusa-workflows/steps/useQueryGraphStep). + * + * ::: + * + * @example + * const data = confirmOrderEditRequestValidationStep({ + * order: { + * id: "order_123", + * // other order details... + * }, + * orderChange: { + * id: "orch_123", + * // other order change details... + * } + * }) */ export const confirmOrderEditRequestValidationStep = createStep( "validate-confirm-order-edit-request", async function ({ order, orderChange, - }: { - order: OrderDTO - orderChange: OrderChangeDTO - }) { + }: ConfirmOrderEditRequestValidationStepInput) { throwIfIsCancelled(order, "Order") throwIfOrderChangeIsNotActive({ orderChange }) } ) +/** + * The data to confirm an order edit request. + */ +export type ConfirmOrderEditRequestWorkflowInput = { + /** + * The ID of the order to confirm the edit for. + */ + order_id: string + /** + * The ID of the user confirming the edit. + */ + confirmed_by?: string +} + export const confirmOrderEditRequestWorkflowId = "confirm-order-edit-request" /** - * This workflow confirms an order edit request. + * This workflow confirms an order edit request. It's used by the + * [Confirm Order Edit Admin API Route](https://docs.medusajs.com/api/admin#order-edits_postordereditsidconfirm). + * + * You can use this workflow within your customizations or your own custom workflows, allowing you to confirm an order edit + * in your custom flow. + * + * @example + * const { result } = await confirmOrderEditRequestWorkflow(container) + * .run({ + * input: { + * order_id: "order_123", + * } + * }) + * + * @summary + * + * Confirm an order edit request. */ export const confirmOrderEditRequestWorkflow = createWorkflow( confirmOrderEditRequestWorkflowId, diff --git a/packages/core/core-flows/src/order/workflows/order-edit/create-order-edit-shipping-method.ts b/packages/core/core-flows/src/order/workflows/order-edit/create-order-edit-shipping-method.ts index 082fa3ddc49a3..96ff0b51be7ba 100644 --- a/packages/core/core-flows/src/order/workflows/order-edit/create-order-edit-shipping-method.ts +++ b/packages/core/core-flows/src/order/workflows/order-edit/create-order-edit-shipping-method.ts @@ -22,35 +22,98 @@ import { prepareShippingMethod } from "../../utils/prepare-shipping-method" import { createOrderChangeActionsWorkflow } from "../create-order-change-actions" import { updateOrderTaxLinesWorkflow } from "../update-tax-lines" +/** + * The data to validate that a shipping method can be created for an order edit. + */ +export type CreateOrderEditShippingMethodValidationStepInput = { + /** + * The order's details. + */ + order: OrderDTO + /** + * The order change's details. + */ + orderChange: OrderChangeDTO +} + /** * This step validates that a shipping method can be created for an order edit. + * If the order is canceled or the order change is not active, the step will throw an error. + * + * :::note + * + * You can retrieve an order and order change details using [Query](https://docs.medusajs.com/learn/fundamentals/module-links/query), + * or [useQueryGraphStep](https://docs.medusajs.com/resources/references/medusa-workflows/steps/useQueryGraphStep). + * + * ::: + * + * @example + * const data = createOrderEditShippingMethodValidationStep({ + * order: { + * id: "order_123", + * // other order details... + * }, + * orderChange: { + * id: "orch_123", + * // other order change details... + * } + * }) */ export const createOrderEditShippingMethodValidationStep = createStep( "validate-create-order-edit-shipping-method", async function ({ order, orderChange, - }: { - order: OrderDTO - orderChange: OrderChangeDTO - }) { + }: CreateOrderEditShippingMethodValidationStepInput) { throwIfIsCancelled(order, "Order") throwIfOrderChangeIsNotActive({ orderChange }) } ) +/** + * The data to create a shipping method for an order edit. + */ +export type CreateOrderEditShippingMethodWorkflowInput = { + /** + * The ID of the order to create the shipping method for. + */ + order_id: string + /** + * The ID of the shipping option to create the shipping method from. + */ + shipping_option_id: string + /** + * The custom amount to create the shipping method with. + * If not provided, the shipping option's amount is used. + */ + custom_amount?: BigNumberInput | null +} + export const createOrderEditShippingMethodWorkflowId = "create-order-edit-shipping-method" /** - * This workflow creates a shipping method for an order edit. + * This workflow creates a shipping method for an order edit. It's used by the + * [Add Shipping Method API Route](https://docs.medusajs.com/api/admin#order-edits_postordereditsidshippingmethod). + * + * You can use this workflow within your customizations or your own custom workflows, allowing you to create a shipping method + * for an order edit in your in your own custom flows. + * + * @example + * const { result } = await createOrderEditShippingMethodWorkflow(container) + * .run({ + * input: { + * order_id: "order_123", + * shipping_option_id: "so_123", + * } + * }) + * + * @summary + * + * Create a shipping method for an order edit. */ export const createOrderEditShippingMethodWorkflow = createWorkflow( createOrderEditShippingMethodWorkflowId, - function (input: { - order_id: string - shipping_option_id: string - custom_amount?: BigNumberInput | null - }): WorkflowResponse { + function (input: CreateOrderEditShippingMethodWorkflowInput): WorkflowResponse { const order: OrderDTO = useRemoteQueryStep({ entry_point: "orders", fields: ["id", "status", "currency_code", "canceled_at"], diff --git a/packages/core/core-flows/src/order/workflows/order-edit/order-edit-add-new-item.ts b/packages/core/core-flows/src/order/workflows/order-edit/order-edit-add-new-item.ts index dfc01889dd3f9..fb63fe25e2dc6 100644 --- a/packages/core/core-flows/src/order/workflows/order-edit/order-edit-add-new-item.ts +++ b/packages/core/core-flows/src/order/workflows/order-edit/order-edit-add-new-item.ts @@ -22,18 +22,49 @@ import { addOrderLineItemsWorkflow } from "../add-line-items" import { createOrderChangeActionsWorkflow } from "../create-order-change-actions" import { updateOrderTaxLinesWorkflow } from "../update-tax-lines" +/** + * The data to validate that new items can be added to an order edit. + */ +export type OrderEditAddNewItemValidationStepInput = { + /** + * The order's details. + */ + order: OrderDTO + /** + * The order change's details. + */ + orderChange: OrderChangeDTO +} + /** * This step validates that new items can be added to an order edit. + * If the order is canceled or the order change is not active, the step will throw an error. + * + * :::note + * + * You can retrieve an order and order change details using [Query](https://docs.medusajs.com/learn/fundamentals/module-links/query), + * or [useQueryGraphStep](https://docs.medusajs.com/resources/references/medusa-workflows/steps/useQueryGraphStep). + * + * ::: + * + * @example + * const data = orderEditAddNewItemValidationStep({ + * order: { + * id: "order_123", + * // other order details... + * }, + * orderChange: { + * id: "orch_123", + * // other order change details... + * } + * }) */ export const orderEditAddNewItemValidationStep = createStep( "order-edit-add-new-item-validation", async function ({ order, orderChange, - }: { - order: OrderDTO - orderChange: OrderChangeDTO - }) { + }: OrderEditAddNewItemValidationStepInput) { throwIfIsCancelled(order, "Order") throwIfOrderChangeIsNotActive({ orderChange }) } @@ -41,7 +72,29 @@ export const orderEditAddNewItemValidationStep = createStep( export const orderEditAddNewItemWorkflowId = "order-edit-add-new-item" /** - * This workflow adds new items to an order edit. + * This workflow adds new items to an order edit. It's used by the + * [Add Items to Order Edit Admin API Route](https://docs.medusajs.com/api/admin#order-edits_postordereditsiditems). + * + * You can use this workflow within your customizations or your own custom workflows, allowing you to add new items to an order edit + * in your custom flows. + * + * @example + * const { result } = await orderEditAddNewItemWorkflow(container) + * .run({ + * input: { + * order_id: "order_123", + * items: [ + * { + * variant_id: "variant_123", + * quantity: 1, + * } + * ] + * } + * }) + * + * @summary + * + * Add new items to an order edit. */ export const orderEditAddNewItemWorkflow = createWorkflow( orderEditAddNewItemWorkflowId, diff --git a/packages/core/core-flows/src/order/workflows/order-edit/order-edit-update-item-quantity.ts b/packages/core/core-flows/src/order/workflows/order-edit/order-edit-update-item-quantity.ts index 176ac2d345a1f..d78e0760c5d66 100644 --- a/packages/core/core-flows/src/order/workflows/order-edit/order-edit-update-item-quantity.ts +++ b/packages/core/core-flows/src/order/workflows/order-edit/order-edit-update-item-quantity.ts @@ -26,17 +26,48 @@ import { import { createOrderChangeActionsWorkflow } from "../create-order-change-actions" /** - * This step validates that item quantity updated can be added to an order edit. + * The data to validate that the quantity of an existing item in an order can be updated in an order edit. + */ +export type OrderEditUpdateItemQuantityValidationStepInput = { + /** + * The order's details. + */ + order: OrderDTO + /** + * The order change's details. + */ + orderChange: OrderChangeDTO +} + +/** + * This step validates that the quantity of an existing item in an order can be updated in an order edit. + * If the order is canceled or the order change is not active, the step will throw an error. + * + * :::note + * + * You can retrieve an order and order change details using [Query](https://docs.medusajs.com/learn/fundamentals/module-links/query), + * or [useQueryGraphStep](https://docs.medusajs.com/resources/references/medusa-workflows/steps/useQueryGraphStep). + * + * ::: + * + * @example + * const data = orderEditUpdateItemQuantityValidationStep({ + * order: { + * id: "order_123", + * // other order details... + * }, + * orderChange: { + * id: "orch_123", + * // other order change details... + * } + * }) */ export const orderEditUpdateItemQuantityValidationStep = createStep( "order-edit-update-item-quantity-validation", async function ({ order, orderChange, - }: { - order: OrderDTO - orderChange: OrderChangeDTO - }) { + }: OrderEditUpdateItemQuantityValidationStepInput) { throwIfIsCancelled(order, "Order") throwIfOrderChangeIsNotActive({ orderChange }) } @@ -45,7 +76,29 @@ export const orderEditUpdateItemQuantityValidationStep = createStep( export const orderEditUpdateItemQuantityWorkflowId = "order-edit-update-item-quantity" /** - * This workflow update item's quantity of an order. + * This workflow updates the quantity of an existing item in an order's edit. It's used by the + * [Update Order Item Quantity Admin API Route](https://docs.medusajs.com/api/admin#order-edits_postordereditsiditemsitemitem_id). + * + * You can use this workflow within your customizations or your own custom workflows, allowing you to update the quantity of an existing + * item in an order's edit in your custom flow. + * + * @example + * const { result } = await orderEditUpdateItemQuantityWorkflow(container) + * .run({ + * input: { + * order_id: "order_123", + * items: [ + * { + * id: "orli_123", + * quantity: 2, + * } + * ] + * } + * }) + * + * @summary + * + * Update the quantity of an existing order item in the order's edit. */ export const orderEditUpdateItemQuantityWorkflow = createWorkflow( orderEditUpdateItemQuantityWorkflowId, diff --git a/packages/core/core-flows/src/order/workflows/order-edit/remove-order-edit-item-action.ts b/packages/core/core-flows/src/order/workflows/order-edit/remove-order-edit-item-action.ts index 5d17b24c45771..ba1881878419b 100644 --- a/packages/core/core-flows/src/order/workflows/order-edit/remove-order-edit-item-action.ts +++ b/packages/core/core-flows/src/order/workflows/order-edit/remove-order-edit-item-action.ts @@ -23,7 +23,50 @@ import { } from "../../utils/order-validation" /** - * This step validates that a new item can be removed from an order edit. + * The data to validate that an item that was added in an order edit can be removed. + */ +export type RemoveOrderEditItemActionValidationStepInput = { + /** + * The order's details. + */ + order: OrderDTO + /** + * The order change's details. + */ + orderChange: OrderChangeDTO + /** + * The details of the item to be removed. + */ + input: OrderWorkflow.DeleteOrderEditItemActionWorkflowInput +} + +/** + * This step validates that an item that was added in the order edit can be removed + * from the order edit. If the order is canceled or the order change is not active, + * the step will throw an error. + * + * :::note + * + * You can retrieve an order and order change details using [Query](https://docs.medusajs.com/learn/fundamentals/module-links/query), + * or [useQueryGraphStep](https://docs.medusajs.com/resources/references/medusa-workflows/steps/useQueryGraphStep). + * + * ::: + * + * @example + * const data = removeOrderEditItemActionValidationStep({ + * order: { + * id: "order_123", + * // other order details... + * }, + * orderChange: { + * id: "orch_123", + * // other order change details... + * }, + * input: { + * order_id: "order_123", + * action_id: "orchact_123", + * } + * }) */ export const removeOrderEditItemActionValidationStep = createStep( "remove-item-order-edit-action-validation", @@ -31,11 +74,7 @@ export const removeOrderEditItemActionValidationStep = createStep( order, orderChange, input, - }: { - order: OrderDTO - orderChange: OrderChangeDTO - input: OrderWorkflow.DeleteOrderEditItemActionWorkflowInput - }) { + }: RemoveOrderEditItemActionValidationStepInput) { throwIfIsCancelled(order, "Order") throwIfOrderChangeIsNotActive({ orderChange }) @@ -62,7 +101,24 @@ export const removeOrderEditItemActionValidationStep = createStep( export const removeItemOrderEditActionWorkflowId = "remove-item-order edit-action" /** - * This workflow removes a new item in an order edit. + * This workflow removes an item that was added to an order edit. It's used by the + * [Remove Item from Order Edit Admin API Route](https://docs.medusajs.com/api/admin#order-edits_deleteordereditsiditemsaction_id). + * + * You can use this workflow within your customizations or your own custom workflows, allowing you to remove an item that was + * added to an order edit in your custom flow. + * + * @example + * const { result } = await removeItemOrderEditActionWorkflow(container) + * .run({ + * input: { + * order_id: "order_123", + * action_id: "orchact_123", + * } + * }) + * + * @summary + * + * Remove an item that was added to an order edit. */ export const removeItemOrderEditActionWorkflow = createWorkflow( removeItemOrderEditActionWorkflowId, diff --git a/packages/core/core-flows/src/order/workflows/order-edit/remove-order-edit-shipping-method.ts b/packages/core/core-flows/src/order/workflows/order-edit/remove-order-edit-shipping-method.ts index 50abf8c7cbb75..f455e34dbb7f8 100644 --- a/packages/core/core-flows/src/order/workflows/order-edit/remove-order-edit-shipping-method.ts +++ b/packages/core/core-flows/src/order/workflows/order-edit/remove-order-edit-shipping-method.ts @@ -19,18 +19,50 @@ import { deleteOrderChangeActionsStep } from "../../steps/delete-order-change-ac import { previewOrderChangeStep } from "../../steps/preview-order-change" import { throwIfOrderChangeIsNotActive } from "../../utils/order-validation" +/** + * The data to validate that a shipping method can be removed from an order edit. + */ +export type RemoveOrderEditShippingMethodValidationStepInput = { + /** + * The order change's details. + */ + orderChange: OrderChangeDTO + /** + * The details of the shipping method to be removed. + */ + input: Pick +} + /** * This step validates that a shipping method can be removed from an order edit. + * If the order change is not active, the shipping method isn't in the exchange, + * or the action doesn't add a shipping method, the step will throw an error. + * + * :::note + * + * You can retrieve an order change details using [Query](https://docs.medusajs.com/learn/fundamentals/module-links/query), + * or [useQueryGraphStep](https://docs.medusajs.com/resources/references/medusa-workflows/steps/useQueryGraphStep). + * + * ::: + * + * @example + * const data = removeOrderEditShippingMethodValidationStep({ + * orderChange: { + * id: "orch_123", + * // other order change details... + * }, + * input: { + * order_id: "order_123", + * action_id: "orchact_123", + * } + * }) */ export const removeOrderEditShippingMethodValidationStep = createStep( "validate-remove-order-edit-shipping-method", async function ({ orderChange, input, - }: { - input: { order_id: string; action_id: string } - orderChange: OrderChangeDTO - }) { + }: RemoveOrderEditShippingMethodValidationStepInput) { throwIfOrderChangeIsNotActive({ orderChange }) const associatedAction = (orderChange.actions ?? []).find( @@ -52,7 +84,24 @@ export const removeOrderEditShippingMethodValidationStep = createStep( export const removeOrderEditShippingMethodWorkflowId = "remove-order-edit-shipping-method" /** - * This workflow removes a shipping method of an order edit. + * This workflow removes a shipping method of an order edit. It's used by the + * [Remove Shipping Method Admin API Route](https://docs.medusajs.com/api/admin#order-edits_deleteordereditsidshippingmethodaction_id). + * + * You can use this workflow within your customizations or your own custom workflows, allowing you to remove a + * shipping method from an order edit in your custom flows. + * + * @example + * const { result } = await removeOrderEditShippingMethodWorkflow(container) + * .run({ + * input: { + * order_id: "order_123", + * action_id: "orchact_123", + * } + * }) + * + * @summary + * + * Remove a shipping method from an order edit. */ export const removeOrderEditShippingMethodWorkflow = createWorkflow( removeOrderEditShippingMethodWorkflowId, diff --git a/packages/core/core-flows/src/order/workflows/order-edit/request-order-edit.ts b/packages/core/core-flows/src/order/workflows/order-edit/request-order-edit.ts index 312c816615312..d289033ef56c7 100644 --- a/packages/core/core-flows/src/order/workflows/order-edit/request-order-edit.ts +++ b/packages/core/core-flows/src/order/workflows/order-edit/request-order-edit.ts @@ -19,11 +19,6 @@ import { } from "../../utils/order-validation" import { createOrUpdateOrderPaymentCollectionWorkflow } from "../create-or-update-order-payment-collection" -export type OrderEditRequestWorkflowInput = { - order_id: string - requested_by?: string -} - function getOrderChangesData({ input, orderChange, @@ -43,26 +38,87 @@ function getOrderChangesData({ }) } +/** + * The data to validate that an order edit can be requested. + */ +export type RequestOrderEditRequestValidationStepInput = { + /** + * The order's details. + */ + order: OrderDTO + /** + * The order change's details. + */ + orderChange: OrderChangeDTO +} + /** * This step validates that a order edit can be requested. + * If the order is canceled or the order change is not active, the step will throw an error. + * + * :::note + * + * You can retrieve an order and order change details using [Query](https://docs.medusajs.com/learn/fundamentals/module-links/query), + * or [useQueryGraphStep](https://docs.medusajs.com/resources/references/medusa-workflows/steps/useQueryGraphStep). + * + * ::: + * + * @example + * const data = requestOrderEditRequestValidationStep({ + * order: { + * id: "order_123", + * // other order details... + * }, + * orderChange: { + * id: "orch_123", + * // other order change details... + * }, + * }) */ export const requestOrderEditRequestValidationStep = createStep( "validate-order-edit-request", async function ({ order, orderChange, - }: { - order: OrderDTO - orderChange: OrderChangeDTO - }) { + }: RequestOrderEditRequestValidationStepInput) { throwIfIsCancelled(order, "Order") throwIfOrderChangeIsNotActive({ orderChange }) } ) +/** + * The data to request an order edit. + */ +export type OrderEditRequestWorkflowInput = { + /** + * The ID of the order to request the edit for. + */ + order_id: string + /** + * The ID of the user requesting the edit. + */ + requested_by?: string +} + export const requestOrderEditRequestWorkflowId = "order-edit-request" /** - * This workflow requests an order edit request. + * This workflow requests a previously created order edit request by {@link beginOrderEditOrderWorkflow}. This workflow is used by + * the [Request Order Edit Admin API Route](https://docs.medusajs.com/api/admin#order-edits_postordereditsidrequest). + * + * You can use this workflow within your customizations or your own custom workflows, allowing you to request an order edit + * in your custom flows. + * + * @example + * const { result } = await requestOrderEditRequestWorkflow(container) + * .run({ + * input: { + * order_id: "order_123", + * } + * }) + * + * @summary + * + * Request an order edit. */ export const requestOrderEditRequestWorkflow = createWorkflow( requestOrderEditRequestWorkflowId, diff --git a/packages/core/core-flows/src/order/workflows/order-edit/update-order-edit-add-item.ts b/packages/core/core-flows/src/order/workflows/order-edit/update-order-edit-add-item.ts index 821d207734c0c..eac3c87513f2f 100644 --- a/packages/core/core-flows/src/order/workflows/order-edit/update-order-edit-add-item.ts +++ b/packages/core/core-flows/src/order/workflows/order-edit/update-order-edit-add-item.ts @@ -24,7 +24,54 @@ import { } from "../../utils/order-validation" /** - * This step validates that a new item can be updated from an order edit. + * The data to validate that a new item can be updated in an order edit. + */ +export type UpdateOrderEditAddItemValidationStepInput = { + /** + * The order's details. + */ + order: OrderDTO + /** + * The order change's details. + */ + orderChange: OrderChangeDTO + /** + * The details of the item to be updated. + */ + input: OrderWorkflow.UpdateOrderEditAddNewItemWorkflowInput +} + +/** + * This step validates that a new item can be updated in an order edit. + * If the order is canceled, the order change is not active, + * the item isn't in the order edit, or the action isn't adding an item, + * the step will throw an error. + * + * :::note + * + * You can retrieve an order and order change details using [Query](https://docs.medusajs.com/learn/fundamentals/module-links/query), + * or [useQueryGraphStep](https://docs.medusajs.com/resources/references/medusa-workflows/steps/useQueryGraphStep). + * + * ::: + * + * @example + * const data = updateOrderEditAddItemValidationStep({ + * order: { + * id: "order_123", + * // other order details... + * }, + * orderChange: { + * id: "orch_123", + * // other order change details... + * }, + * input: { + * order_id: "order_123", + * action_id: "orchac_123", + * data: { + * quantity: 1, + * } + * } + * }) */ export const updateOrderEditAddItemValidationStep = createStep( "update-order-edit-add-item-validation", @@ -33,11 +80,7 @@ export const updateOrderEditAddItemValidationStep = createStep( order, orderChange, input, - }: { - order: OrderDTO - orderChange: OrderChangeDTO - input: OrderWorkflow.UpdateOrderEditAddNewItemWorkflowInput - }, + }: UpdateOrderEditAddItemValidationStepInput, context ) { throwIfIsCancelled(order, "Order") @@ -59,7 +102,27 @@ export const updateOrderEditAddItemValidationStep = createStep( export const updateOrderEditAddItemWorkflowId = "update-order-edit-add-item" /** - * This workflow updates a new item in the order edit. + * This workflow updates a new item in an order edit. It's used by the + * [Update Item Admin API Route](https://docs.medusajs.com/api/admin#order-edits_postordereditsiditemsaction_id). + * + * You can use this workflow within your customizations or your own custom workflows, allowing you to update a new item in an order edit + * in your custom flows. + * + * @example + * const { result } = await updateOrderEditAddItemWorkflow(container) + * .run({ + * input: { + * order_id: "order_123", + * action_id: "orchac_123", + * data: { + * quantity: 1, + * } + * } + * }) + * + * @summary + * + * Update a new item in an order edit. */ export const updateOrderEditAddItemWorkflow = createWorkflow( updateOrderEditAddItemWorkflowId, diff --git a/packages/core/core-flows/src/order/workflows/order-edit/update-order-edit-item-quantity.ts b/packages/core/core-flows/src/order/workflows/order-edit/update-order-edit-item-quantity.ts index 6f83b2e26fe81..71cef3b44f4b4 100644 --- a/packages/core/core-flows/src/order/workflows/order-edit/update-order-edit-item-quantity.ts +++ b/packages/core/core-flows/src/order/workflows/order-edit/update-order-edit-item-quantity.ts @@ -24,7 +24,54 @@ import { } from "../../utils/order-validation" /** - * This step validates that an item can be updated from an order edit. + * The data to validate that an existing order item can be updated in an order edit. + */ +export type UpdateOrderEditItemQuantityValidationStepInput = { + /** + * The order's details. + */ + order: OrderDTO + /** + * The order change's details. + */ + orderChange: OrderChangeDTO + /** + * The details of the item to be updated. + */ + input: OrderWorkflow.UpdateOrderEditItemQuantityWorkflowInput +} + +/** + * This step validates that an existing order item can be updated in an order edit. + * If the order is canceled, the order change is not active, + * the item isn't in the order edit, or the action isn't updating an existing item, + * the step will throw an error. + * + * :::note + * + * You can retrieve an order and order change details using [Query](https://docs.medusajs.com/learn/fundamentals/module-links/query), + * or [useQueryGraphStep](https://docs.medusajs.com/resources/references/medusa-workflows/steps/useQueryGraphStep). + * + * ::: + * + * @example + * const data = updateOrderEditItemQuantityValidationStep({ + * order: { + * id: "order_123", + * // other order details... + * }, + * orderChange: { + * id: "orch_123", + * // other order change details... + * }, + * input: { + * order_id: "order_123", + * action_id: "orchac_123", + * data: { + * quantity: 1, + * } + * } + * }) */ export const updateOrderEditItemQuantityValidationStep = createStep( "update-order-edit-update-quantity-validation", @@ -33,11 +80,7 @@ export const updateOrderEditItemQuantityValidationStep = createStep( order, orderChange, input, - }: { - order: OrderDTO - orderChange: OrderChangeDTO - input: OrderWorkflow.UpdateOrderEditItemQuantityWorkflowInput - }, + }: UpdateOrderEditItemQuantityValidationStepInput, context ) { throwIfIsCancelled(order, "Order") @@ -60,7 +103,26 @@ export const updateOrderEditItemQuantityValidationStep = createStep( export const updateOrderEditItemQuantityWorkflowId = "update-order-edit-update-quantity" /** - * This workflow updates a new item in the order edit. + * This workflow updates an existing order item that was previously added to the order edit. + * + * You can use this workflow within your customizations or your own custom workflows, allowing you to update the quantity + * of an existing item in an order edit in your custom flows. + * + * @example + * const { result } = await updateOrderEditItemQuantityWorkflow(container) + * .run({ + * input: { + * order_id: "order_123", + * action_id: "orchac_123", + * data: { + * quantity: 1, + * } + * } + * }) + * + * @summary + * + * Update an existing order item previously added to an order edit. */ export const updateOrderEditItemQuantityWorkflow = createWorkflow( updateOrderEditItemQuantityWorkflowId, diff --git a/packages/core/core-flows/src/order/workflows/order-edit/update-order-edit-shipping-method.ts b/packages/core/core-flows/src/order/workflows/order-edit/update-order-edit-shipping-method.ts index 433fbbb11aece..05e2233862643 100644 --- a/packages/core/core-flows/src/order/workflows/order-edit/update-order-edit-shipping-method.ts +++ b/packages/core/core-flows/src/order/workflows/order-edit/update-order-edit-shipping-method.ts @@ -24,18 +24,53 @@ import { previewOrderChangeStep } from "../../steps/preview-order-change" import { throwIfOrderChangeIsNotActive } from "../../utils/order-validation" import { prepareShippingMethodUpdate } from "../../utils/prepare-shipping-method" +/** + * The data to validate that an order edit's shipping method can be updated. + */ +export type UpdateOrderEditShippingMethodValidationStepInput = { + /** + * The order change's details. + */ + orderChange: OrderChangeDTO + /** + * The details of the shipping method to be updated. + */ + input: Pick +} + /** * This step validates that an order edit's shipping method can be updated. + * If the order change is not active, the shipping method isn't in the order edit, + * or the action is not adding a shipping method, the step will throw an error. + * + * :::note + * + * You can retrieve an order change details using [Query](https://docs.medusajs.com/learn/fundamentals/module-links/query), + * or [useQueryGraphStep](https://docs.medusajs.com/resources/references/medusa-workflows/steps/useQueryGraphStep). + * + * ::: + * + * @example + * const data = updateOrderEditShippingMethodValidationStep({ + * orderChange: { + * id: "orch_123", + * // other order change details... + * }, + * input: { + * order_id: "order_123", + * action_id: "orchac_123", + * data: { + * custom_amount: 10, + * } + * } + * }) */ export const updateOrderEditShippingMethodValidationStep = createStep( "validate-update-order-edit-shipping-method", async function ({ orderChange, input, - }: { - input: { order_id: string; action_id: string } - orderChange: OrderChangeDTO - }) { + }: UpdateOrderEditShippingMethodValidationStepInput) { throwIfOrderChangeIsNotActive({ orderChange }) const associatedAction = (orderChange.actions ?? []).find( @@ -57,7 +92,27 @@ export const updateOrderEditShippingMethodValidationStep = createStep( export const updateOrderEditShippingMethodWorkflowId = "update-order-edit-shipping-method" /** - * This workflow updates an order edit's shipping method. + * This workflow updates an order edit's shipping method. It's used by the + * [Update Shipping Method Admin API Route](https://docs.medusajs.com/api/admin#order-edits_postordereditsidshippingmethodaction_id). + * + * You can use this workflow within your customizations or your own custom workflows, allowing you to update an order edit's shipping method + * in your custom flow. + * + * @example + * const { result } = await updateOrderEditShippingMethodWorkflow(container) + * .run({ + * input: { + * order_id: "order_123", + * action_id: "orchac_123", + * data: { + * custom_amount: 10, + * } + * } + * }) + * + * @summary + * + * Update a shipping method of an order edit. */ export const updateOrderEditShippingMethodWorkflow = createWorkflow( updateOrderEditShippingMethodWorkflowId, diff --git a/packages/core/core-flows/src/order/workflows/return/begin-receive-return.ts b/packages/core/core-flows/src/order/workflows/return/begin-receive-return.ts index 02e4b74defd43..9510092f72691 100644 --- a/packages/core/core-flows/src/order/workflows/return/begin-receive-return.ts +++ b/packages/core/core-flows/src/order/workflows/return/begin-receive-return.ts @@ -15,8 +15,42 @@ import { useRemoteQueryStep } from "../../../common" import { createOrderChangeStep } from "../../steps" import { throwIfIsCancelled } from "../../utils/order-validation" +/** + * The data to validate that a return can be received. + */ +export type BeginReceiveReturnValidationStepInput = { + /** + * The order return's details. + */ + orderReturn: ReturnDTO + /** + * The order's details. + */ + order: OrderDTO +} + /** * This step validates that a return can be received. + * If the order or return is canceled, the step will throw an error. + * + * :::note + * + * You can retrieve an order and return details using [Query](https://docs.medusajs.com/learn/fundamentals/module-links/query), + * or [useQueryGraphStep](https://docs.medusajs.com/resources/references/medusa-workflows/steps/useQueryGraphStep). + * + * ::: + * + * @example + * const data = beginReceiveReturnValidationStep({ + * orderReturn: { + * id: "return_123", + * // other order return details... + * }, + * order: { + * id: "order_123", + * // other order details... + * } + * }) */ export const beginReceiveReturnValidationStep = createStep( "begin-receive-return-validation", @@ -24,10 +58,7 @@ export const beginReceiveReturnValidationStep = createStep( { orderReturn, order, - }: { - orderReturn: ReturnDTO - order: OrderDTO - }, + }: BeginReceiveReturnValidationStepInput, context ) { throwIfIsCancelled(order, "Order") @@ -37,7 +68,25 @@ export const beginReceiveReturnValidationStep = createStep( export const beginReceiveReturnWorkflowId = "begin-receive-return" /** - * This workflow requests return receival. + * This workflow requests return receival. It's used by the + * [Start Return Receival Admin API Route](https://docs.medusajs.com/api/admin#returns_postreturnsidreceive). + * + * You can confirm the return receival using the {@link confirmReturnRequestWorkflow}. + * + * You can use this workflow within your customizations or your own custom workflows, allowing you + * to receive a return in your custom flows. + * + * @example + * const { result } = await beginReceiveReturnWorkflow(container) + * .run({ + * input: { + * return_id: "return_123", + * } + * }) + * + * @summary + * + * Request a return receival. */ export const beginReceiveReturnWorkflow = createWorkflow( beginReceiveReturnWorkflowId, diff --git a/packages/core/core-flows/src/order/workflows/return/begin-return.ts b/packages/core/core-flows/src/order/workflows/return/begin-return.ts index d31c8e98bfa6c..1bf366db10b27 100644 --- a/packages/core/core-flows/src/order/workflows/return/begin-return.ts +++ b/packages/core/core-flows/src/order/workflows/return/begin-return.ts @@ -14,19 +14,63 @@ import { useRemoteQueryStep } from "../../../common" import { createOrderChangeStep, createReturnsStep } from "../../steps" import { throwIfOrderIsCancelled } from "../../utils/order-validation" +/** + * The data to validate that a return can be created for an order. + */ +export type BeginReturnOrderValidationStepInput = { + /** + * The order's details. + */ + order: OrderDTO +} + /** * This step validates that a return can be created for an order. + * If the order is canceled, the step will throw an error. + * + * :::note + * + * You can retrieve an order details using [Query](https://docs.medusajs.com/learn/fundamentals/module-links/query), + * or [useQueryGraphStep](https://docs.medusajs.com/resources/references/medusa-workflows/steps/useQueryGraphStep). + * + * ::: + * + * @example + * const data = beginReturnOrderValidationStep({ + * order: { + * id: "order_123", + * // other order details... + * } + * }) */ export const beginReturnOrderValidationStep = createStep( "begin-return-order-validation", - async function ({ order }: { order: OrderDTO }) { + async function ({ order }: BeginReturnOrderValidationStepInput) { throwIfOrderIsCancelled({ order }) } ) export const beginReturnOrderWorkflowId = "begin-return-order" /** - * This workflow requests a return. + * This workflow creates an order return that can be later requested or confirmed. + * It's used by the [Create Return Admin API Route](https://docs.medusajs.com/api/admin#returns_postreturns). + * + * You can start the return receival using the {@link beginReceiveReturnWorkflow}. + * + * You can use this workflow within your customizations or your own custom workflows, allowing you + * to create a return for an order in your custom flow. + * + * @example + * const { result } = await beginReturnOrderWorkflow(container) + * .run({ + * input: { + * order_id: "order_123" + * } + * }) + * + * @summary + * + * Create a return for an order. */ export const beginReturnOrderWorkflow = createWorkflow( beginReturnOrderWorkflowId, diff --git a/packages/core/core-flows/src/order/workflows/return/cancel-receive-return.ts b/packages/core/core-flows/src/order/workflows/return/cancel-receive-return.ts index 0fb672a5d652c..6f21d69566c89 100644 --- a/packages/core/core-flows/src/order/workflows/return/cancel-receive-return.ts +++ b/packages/core/core-flows/src/order/workflows/return/cancel-receive-return.ts @@ -12,8 +12,50 @@ import { throwIfOrderChangeIsNotActive, } from "../../utils/order-validation" +/** + * The data to validate that a return receival can be canceled. + */ +export type CancelReceiveReturnValidationStepInput = { + /** + * The order's details. + */ + order: OrderDTO + /** + * The order change's details. + */ + orderChange: OrderChangeDTO + /** + * The order return's details. + */ + orderReturn: ReturnDTO +} + /** * This step validates that a return receival can be canceled. + * If the order or return is canceled, or the order change is not active, the step will throw an error. + * + * :::note + * + * You can retrieve an order, return, and order change details using [Query](https://docs.medusajs.com/learn/fundamentals/module-links/query), + * or [useQueryGraphStep](https://docs.medusajs.com/resources/references/medusa-workflows/steps/useQueryGraphStep). + * + * ::: + * + * @example + * const data = cancelReceiveReturnValidationStep({ + * order: { + * id: "order_123", + * // other order details... + * }, + * orderChange: { + * id: "orch_123", + * // other order change details... + * }, + * orderReturn: { + * id: "return_123", + * // other order return details... + * } + * }) */ export const cancelReceiveReturnValidationStep = createStep( "validate-cancel-return-shipping-method", @@ -21,24 +63,46 @@ export const cancelReceiveReturnValidationStep = createStep( order, orderChange, orderReturn, - }: { - order: OrderDTO - orderReturn: ReturnDTO - orderChange: OrderChangeDTO - }) { + }: CancelReceiveReturnValidationStepInput) { throwIfIsCancelled(order, "Order") throwIfIsCancelled(orderReturn, "Return") throwIfOrderChangeIsNotActive({ orderChange }) } ) +/** + * The data to cancel a return receival. + */ +export type CancelReturnReceiveWorkflowInput = { + /** + * The ID of the return to cancel the receival for. + */ + return_id: string +} + export const cancelReturnReceiveWorkflowId = "cancel-receive-return" /** - * This workflow cancels a return receival. + * This workflow cancels a return receival. It's used by the + * [Cancel Return Receival Admin API Route](https://docs.medusajs.com/api/admin#returns_deletereturnsidreceive). + * + * You can use this workflow within your customizations or your own custom workflows, allowing you + * to cancel a return receival in your custom flow. + * + * @example + * const { result } = await cancelReturnReceiveWorkflow(container) + * .run({ + * input: { + * return_id: "return_123", + * } + * }) + * + * @summary + * + * Cancel a return receival. */ export const cancelReturnReceiveWorkflow = createWorkflow( cancelReturnReceiveWorkflowId, - function (input: { return_id: string }): WorkflowData { + function (input: CancelReturnReceiveWorkflowInput): WorkflowData { const orderReturn: ReturnDTO = useRemoteQueryStep({ entry_point: "return", fields: ["id", "status", "order_id", "canceled_at"], diff --git a/packages/core/core-flows/src/order/workflows/return/cancel-request-return.ts b/packages/core/core-flows/src/order/workflows/return/cancel-request-return.ts index d31ecc327bb1f..7ddd756b5d081 100644 --- a/packages/core/core-flows/src/order/workflows/return/cancel-request-return.ts +++ b/packages/core/core-flows/src/order/workflows/return/cancel-request-return.ts @@ -18,12 +18,51 @@ import { throwIfOrderChangeIsNotActive, } from "../../utils/order-validation" -export type CancelRequestReturnWorkflowInput = { - return_id: string +/** + * The data to validate that a requested return can be canceled. + */ +export type CancelRequestReturnValidationStepInput = { + /** + * The order's details. + */ + order: OrderDTO + /** + * The order change's details. + */ + orderChange: OrderChangeDTO + /** + * The order return's details. + */ + orderReturn: ReturnDTO } /** * This step validates that a requested return can be canceled. + * If the order or return is canceled, or the order change is not active, + * the step will throw an error. + * + * :::note + * + * You can retrieve an order, return, and order change details using [Query](https://docs.medusajs.com/learn/fundamentals/module-links/query), + * or [useQueryGraphStep](https://docs.medusajs.com/resources/references/medusa-workflows/steps/useQueryGraphStep). + * + * ::: + * + * @example + * const data = cancelRequestReturnValidationStep({ + * order: { + * id: "order_123", + * // other order details... + * }, + * orderChange: { + * id: "orch_123", + * // other order change details... + * }, + * orderReturn: { + * id: "return_123", + * // other order return details... + * } + * }) */ export const cancelRequestReturnValidationStep = createStep( "validate-cancel-return-shipping-method", @@ -31,20 +70,42 @@ export const cancelRequestReturnValidationStep = createStep( order, orderChange, orderReturn, - }: { - order: OrderDTO - orderReturn: ReturnDTO - orderChange: OrderChangeDTO - }) { + }: CancelRequestReturnValidationStepInput) { throwIfIsCancelled(order, "Order") throwIfIsCancelled(orderReturn, "Return") throwIfOrderChangeIsNotActive({ orderChange }) } ) +/** + * The data to cancel a requested return. + */ +export type CancelRequestReturnWorkflowInput = { + /** + * The ID of the return to cancel. + */ + return_id: string +} + export const cancelReturnRequestWorkflowId = "cancel-return-request" /** - * This workflow cancels a requested return. + * This workflow cancels a requested return. It's used by the + * [Cancel Return Request API Route](https://docs.medusajs.com/api/admin#returns_deletereturnsidrequest). + * + * You can use this workflow within your customizations or your own custom workflows, allowing you + * to cancel a return request in your custom flow. + * + * @example + * const { result } = await cancelReturnRequestWorkflow(container) + * .run({ + * input: { + * return_id: "return_123", + * } + * }) + * + * @summary + * + * Cancel a requested return. */ export const cancelReturnRequestWorkflow = createWorkflow( cancelReturnRequestWorkflowId, diff --git a/packages/core/core-flows/src/order/workflows/return/cancel-return.ts b/packages/core/core-flows/src/order/workflows/return/cancel-return.ts index ad66765f8230a..b7129c6bffc33 100644 --- a/packages/core/core-flows/src/order/workflows/return/cancel-return.ts +++ b/packages/core/core-flows/src/order/workflows/return/cancel-return.ts @@ -14,17 +14,48 @@ import { useRemoteQueryStep } from "../../../common" import { cancelOrderReturnStep } from "../../steps" import { throwIfIsCancelled } from "../../utils/order-validation" +/** + * The data to validate that a return can be canceled. + */ +export type CancelReturnValidateOrderInput = { + /** + * The order return's details. + */ + orderReturn: ReturnDTO + /** + * The data to cancel a return. + */ + input: OrderWorkflow.CancelReturnWorkflowInput +} + /** * This step validates that a return can be canceled. + * If the return is canceled, its fulfillment aren't canceled, + * or it has received items, the step will throw an error. + * + * :::note + * + * You can retrieve a return details using [Query](https://docs.medusajs.com/learn/fundamentals/module-links/query), + * or [useQueryGraphStep](https://docs.medusajs.com/resources/references/medusa-workflows/steps/useQueryGraphStep). + * + * ::: + * + * @example + * const data = cancelReturnValidateOrder({ + * orderReturn: { + * id: "return_123", + * // other order return details... + * }, + * input: { + * return_id: "return_123" + * } + * }) */ export const cancelReturnValidateOrder = createStep( "validate-return", ({ orderReturn, - }: { - orderReturn: ReturnDTO - input: OrderWorkflow.CancelReturnWorkflowInput - }) => { + }: CancelReturnValidateOrderInput) => { const orderReturn_ = orderReturn as ReturnDTO & { payment_collections: PaymentCollectionDTO[] fulfillments: FulfillmentDTO[] @@ -61,7 +92,19 @@ export const cancelReturnValidateOrder = createStep( export const cancelReturnWorkflowId = "cancel-return" /** - * This workflow cancels a return. + * This workflow cancels a return. It's used by the + * [Cancel Return Admin API Route](https://docs.medusajs.com/api/admin#returns_postreturnsidcancel). + * + * You can use this workflow within your customizations or your own custom workflows, allowing you + * to cancel a return in your custom flow. + * + * @example + * const { result } = await cancelReturnWorkflow(container) + * .run({ + * input: { + * return_id: "return_123", + * } + * }) */ export const cancelReturnWorkflow = createWorkflow( cancelReturnWorkflowId, diff --git a/packages/core/core-flows/src/order/workflows/return/confirm-receive-return-request.ts b/packages/core/core-flows/src/order/workflows/return/confirm-receive-return-request.ts index 64a1c94bcc66e..7eb51b58d3953 100644 --- a/packages/core/core-flows/src/order/workflows/return/confirm-receive-return-request.ts +++ b/packages/core/core-flows/src/order/workflows/return/confirm-receive-return-request.ts @@ -35,13 +35,50 @@ import { throwIfOrderChangeIsNotActive, } from "../../utils/order-validation" -export type ConfirmReceiveReturnRequestWorkflowInput = { - return_id: string - confirmed_by?: string +/** + * The data to validate that a return receival can be confirmed. + */ +export type ConfirmReceiveReturnValidationStepInput = { + /** + * The order's details. + */ + order: OrderDTO + /** + * The order return's details. + */ + orderReturn: ReturnDTO + /** + * The order change's details. + */ + orderChange: OrderChangeDTO } /** * This step validates that a return receival can be confirmed. + * If the order or return is canceled, or the order change is not active, the step will throw an error. + * + * :::note + * + * You can retrieve an order, return, and order change details using [Query](https://docs.medusajs.com/learn/fundamentals/module-links/query), + * or [useQueryGraphStep](https://docs.medusajs.com/resources/references/medusa-workflows/steps/useQueryGraphStep). + * + * ::: + * + * @example + * const data = confirmReceiveReturnValidationStep({ + * order: { + * id: "order_123", + * // other order details... + * }, + * orderReturn: { + * id: "return_123", + * // other order return details... + * }, + * orderChange: { + * id: "orch_123", + * // other order change details... + * } + * }) */ export const confirmReceiveReturnValidationStep = createStep( "validate-confirm-return-receive", @@ -49,11 +86,7 @@ export const confirmReceiveReturnValidationStep = createStep( order, orderChange, orderReturn, - }: { - order: OrderDTO - orderReturn: ReturnDTO - orderChange: OrderChangeDTO - }) { + }: ConfirmReceiveReturnValidationStepInput) { throwIfIsCancelled(order, "Order") throwIfIsCancelled(orderReturn, "Return") throwIfOrderChangeIsNotActive({ orderChange }) @@ -131,9 +164,39 @@ function prepareInventoryUpdate({ orderReturn, returnedQuantityMap }) { return inventoryAdjustment } +/** + * The data to confirm a return receival request. + */ +export type ConfirmReceiveReturnRequestWorkflowInput = { + /** + * The ID of the return to confirm the receival for. + */ + return_id: string + /** + * The ID of the user that's confirming the return receival. + */ + confirmed_by?: string +} + export const confirmReturnReceiveWorkflowId = "confirm-return-receive" /** - * This workflow confirms a return receival request. + * This workflow confirms a return receival request. It's used by the + * [Confirm Return Receival Admin API Route](https://docs.medusajs.com/api/admin#returns_postreturnsidreceiveconfirm). + * + * You can use this workflow within your customizations or your own custom workflows, allowing you + * to confirm a return receival in your custom flow. + * + * @example + * const { result } = await confirmReturnReceiveWorkflow(container) + * .run({ + * input: { + * return_id: "return_123", + * } + * }) + * + * @summary + * + * Confirm a return receival request. */ export const confirmReturnReceiveWorkflow = createWorkflow( confirmReturnReceiveWorkflowId, diff --git a/packages/core/core-flows/src/order/workflows/return/confirm-return-request.ts b/packages/core/core-flows/src/order/workflows/return/confirm-return-request.ts index 3ee2aa1345afd..b500e0dd1acc3 100644 --- a/packages/core/core-flows/src/order/workflows/return/confirm-return-request.ts +++ b/packages/core/core-flows/src/order/workflows/return/confirm-return-request.ts @@ -37,13 +37,50 @@ import { } from "../../utils/order-validation" import { createOrUpdateOrderPaymentCollectionWorkflow } from "../create-or-update-order-payment-collection" -export type ConfirmReturnRequestWorkflowInput = { - return_id: string - confirmed_by?: string +/** + * The data to validate that a return request can be confirmed. + */ +export type ConfirmReturnRequestValidationStepInput = { + /** + * The order's details. + */ + order: OrderDTO + /** + * The order return's details. + */ + orderReturn: ReturnDTO + /** + * The order change's details. + */ + orderChange: OrderChangeDTO } /** * This step validates that a return request can be confirmed. + * If the order or return is canceled or the order change is not active, the step will throw an error. + * + * :::note + * + * You can retrieve an order, order change, and return details using [Query](https://docs.medusajs.com/learn/fundamentals/module-links/query), + * or [useQueryGraphStep](https://docs.medusajs.com/resources/references/medusa-workflows/steps/useQueryGraphStep). + * + * ::: + * + * @example + * const data = confirmReturnRequestValidationStep({ + * order: { + * id: "order_123", + * // other order details... + * }, + * orderReturn: { + * id: "return_123", + * // other order return details... + * }, + * orderChange: { + * id: "orch_123", + * // other order change details... + * } + * }) */ export const confirmReturnRequestValidationStep = createStep( "validate-confirm-return-request", @@ -51,11 +88,7 @@ export const confirmReturnRequestValidationStep = createStep( order, orderChange, orderReturn, - }: { - order: OrderDTO - orderReturn: ReturnDTO - orderChange: OrderChangeDTO - }) { + }: ConfirmReturnRequestValidationStepInput) { throwIfIsCancelled(order, "Order") throwIfIsCancelled(orderReturn, "Return") throwIfOrderChangeIsNotActive({ orderChange }) @@ -170,9 +203,39 @@ function getUpdateReturnData({ orderReturn }: { orderReturn: { id: string } }) { }) } +/** + * The details of confirming a return request. + */ +export type ConfirmReturnRequestWorkflowInput = { + /** + * The ID of the return to confirm its request. + */ + return_id: string + /** + * The ID of the user confirming the return request. + */ + confirmed_by?: string +} + export const confirmReturnRequestWorkflowId = "confirm-return-request" /** - * This workflow confirms a return request. + * This workflow confirms a return request. It's used by the + * [Confirm Return Request Admin API Route](https://docs.medusajs.com/api/admin#returns_postreturnsidrequest). + * + * You can use this workflow within your customizations or your own custom workflows, allowing you to confirm a return request + * in your custom flow. + * + * @example + * const { result } = await confirmReturnRequestWorkflow(container) + * .run({ + * input: { + * return_id: "return_123", + * } + * }) + * + * @summary + * + * Confirm a return request. */ export const confirmReturnRequestWorkflow = createWorkflow( confirmReturnRequestWorkflowId, diff --git a/packages/core/core-flows/src/order/workflows/return/create-complete-return.ts b/packages/core/core-flows/src/order/workflows/return/create-complete-return.ts index ac6c0c4251cac..dcc1a29163287 100644 --- a/packages/core/core-flows/src/order/workflows/return/create-complete-return.ts +++ b/packages/core/core-flows/src/order/workflows/return/create-complete-return.ts @@ -209,8 +209,49 @@ function prepareReturnShippingOptionQueryVariables({ return variables } +/** + * The data to validate that a return can be created and completed. + */ +export type CreateCompleteReturnValidationStepInput = { + /** + * The order's details. + */ + order + /** + * The data to create a return. + */ + input: OrderWorkflow.CreateOrderReturnWorkflowInput +} + /** * This step validates that a return can be created and completed for an order. + * If the order is canceled, the items do not exist in the order, + * the return reasons are invalid, or the refund amount is greater than the order total, + * the step will throw an error. + * + * :::note + * + * You can retrieve an order details using [Query](https://docs.medusajs.com/learn/fundamentals/module-links/query), + * or [useQueryGraphStep](https://docs.medusajs.com/resources/references/medusa-workflows/steps/useQueryGraphStep). + * + * ::: + * + * @example + * const data = createCompleteReturnValidationStep({ + * order: { + * id: "order_123", + * // other order details... + * }, + * input: { + * order_id: "order_123", + * items: [ + * { + * id: "orli_123", + * quantity: 1, + * } + * ] + * } + * }) */ export const createCompleteReturnValidationStep = createStep( "create-return-order-validation", @@ -218,10 +259,7 @@ export const createCompleteReturnValidationStep = createStep( { order, input, - }: { - order - input: OrderWorkflow.CreateOrderReturnWorkflowInput - }, + }: CreateCompleteReturnValidationStepInput, context ) { if (!input.items) { @@ -244,7 +282,30 @@ export const createCompleteReturnValidationStep = createStep( export const createAndCompleteReturnOrderWorkflowId = "create-complete-return-order" /** - * This workflow creates and completes a return. + * This workflow creates and completes a return from the storefront. The admin would receive the return and + * process it from the dashboard. This workflow is used by the + * [Create Return Store API Route](https://docs.medusajs.com/api/store#return_postreturn). + * + * You can use this workflow within your customizations or your own custom workflows, allowing you to create a return + * for an order in your custom flow. + * + * @example + * const { result } = await createAndCompleteReturnOrderWorkflow(container) + * .run({ + * input: { + * order_id: "order_123", + * items: [ + * { + * id: "orli_123", + * quantity: 1, + * } + * ] + * } + * }) + * + * @summary + * + * Create and complete a return for an order. */ export const createAndCompleteReturnOrderWorkflow = createWorkflow( createAndCompleteReturnOrderWorkflowId, diff --git a/packages/core/core-flows/src/order/workflows/return/create-return-shipping-method.ts b/packages/core/core-flows/src/order/workflows/return/create-return-shipping-method.ts index dd698c2759071..8e46c3fe46553 100644 --- a/packages/core/core-flows/src/order/workflows/return/create-return-shipping-method.ts +++ b/packages/core/core-flows/src/order/workflows/return/create-return-shipping-method.ts @@ -23,8 +23,50 @@ import { prepareShippingMethod } from "../../utils/prepare-shipping-method" import { createOrderChangeActionsWorkflow } from "../create-order-change-actions" import { updateOrderTaxLinesWorkflow } from "../update-tax-lines" +/** + * The data to validate that a shipping method can be created for a return. + */ +export type CreateReturnShippingMethodValidationStepInput = { + /** + * The order's details. + */ + order: OrderDTO + /** + * The return's details. + */ + orderReturn: ReturnDTO + /** + * The order change's details. + */ + orderChange: OrderChangeDTO +} + /** * This step validates that a shipping method can be created for a return. + * If the order or return is canceled, or the order change is not active, the step will throw an error. + * + * :::note + * + * You can retrieve an order, return, and order change details using [Query](https://docs.medusajs.com/learn/fundamentals/module-links/query), + * or [useQueryGraphStep](https://docs.medusajs.com/resources/references/medusa-workflows/steps/useQueryGraphStep). + * + * ::: + * + * @example + * const data = createReturnShippingMethodValidationStep({ + * order: { + * id: "order_123", + * // other order details... + * }, + * orderReturn: { + * id: "return_123", + * // other return details... + * }, + * orderChange: { + * id: "orch_123", + * // other order change details... + * }, + * }) */ export const createReturnShippingMethodValidationStep = createStep( "validate-create-return-shipping-method", @@ -32,31 +74,65 @@ export const createReturnShippingMethodValidationStep = createStep( order, orderChange, orderReturn, - }: { - order: OrderDTO - orderReturn: ReturnDTO - orderChange: OrderChangeDTO - }) { + }: CreateReturnShippingMethodValidationStepInput) { throwIfIsCancelled(order, "Order") throwIfIsCancelled(orderReturn, "Return") throwIfOrderChangeIsNotActive({ orderChange }) } ) +/** + * The data to create a shipping method for a return. + */ +export type CreateReturnShippingMethodWorkflowInput = { + /** + * The ID of the return to create the shipping method for. + */ + return_id: string + /** + * The ID of the claim associated with the return, if any. + */ + claim_id?: string + /** + * The ID of the exchange associated with the return, if any. + */ + exchange_id?: string + /** + * The ID of the shipping option to create the shipping method from. + */ + shipping_option_id: string + /** + * The custom amount to charge for the shipping method. + * If not provided, the amount from the shipping option will be used. + */ + custom_amount?: BigNumberInput | null +} + export const createReturnShippingMethodWorkflowId = "create-return-shipping-method" /** - * This workflow creates a shipping method for a return. + * This workflow creates a shipping method for a return. It's used by the + * [Add Shipping Method Store API Route](https://docs.medusajs.com/api/admin#returns_postreturnsidshippingmethod). + * + * You can use this workflow within your customizations or your own custom workflows, allowing you + * to create a shipping method for a return in your custom flows. + * + * @example + * const { result } = await createReturnShippingMethodWorkflow(container) + * .run({ + * input: { + * return_id: "return_123", + * shipping_option_id: "so_123", + * } + * }) + * + * @summary + * + * Create a shipping method for a return. */ export const createReturnShippingMethodWorkflow = createWorkflow( createReturnShippingMethodWorkflowId, - function (input: { - return_id: string - claim_id?: string - exchange_id?: string - shipping_option_id: string - custom_amount?: BigNumberInput | null - }): WorkflowResponse { + function (input: CreateReturnShippingMethodWorkflowInput): WorkflowResponse { const orderReturn: ReturnDTO = useRemoteQueryStep({ entry_point: "return", fields: [ diff --git a/packages/core/core-flows/src/order/workflows/return/dismiss-item-return-request.ts b/packages/core/core-flows/src/order/workflows/return/dismiss-item-return-request.ts index 32d73a8a1fc3d..75b0e171174a1 100644 --- a/packages/core/core-flows/src/order/workflows/return/dismiss-item-return-request.ts +++ b/packages/core/core-flows/src/order/workflows/return/dismiss-item-return-request.ts @@ -22,8 +22,66 @@ import { } from "../../utils/order-validation" import { createOrderChangeActionsWorkflow } from "../create-order-change-actions" +/** + * The data to validate that a return request can have its items dismissed. + */ +export type DismissItemReturnRequestValidationStepInput = { + /** + * The order's details. + */ + order: Pick + /** + * The return's details. + */ + orderReturn: ReturnDTO + /** + * The order change's details. + */ + orderChange: OrderChangeDTO + /** + * The items to dismiss. + */ + items: OrderWorkflow.ReceiveOrderReturnItemsWorkflowInput["items"] +} + /** * This step validates that a return request can have its items dismissed. + * If the order or return is canceled, the order change is not active, + * or the items do not exist in the return, the step will throw an error. + * + * :::note + * + * You can retrieve an order, return, and order change details using [Query](https://docs.medusajs.com/learn/fundamentals/module-links/query), + * or [useQueryGraphStep](https://docs.medusajs.com/resources/references/medusa-workflows/steps/useQueryGraphStep). + * + * ::: + * + * @example + * const data = dismissItemReturnRequestValidationStep({ + * order: { + * id: "order_123", + * items: [ + * { + * id: "orli_123", + * // other item details... + * } + * ] + * }, + * orderReturn: { + * id: "return_123", + * // other return details... + * }, + * orderChange: { + * id: "orch_123", + * // other order change details... + * }, + * items: [ + * { + * id: "orli_123", + * quantity: 1, + * } + * ] + * }) */ export const dismissItemReturnRequestValidationStep = createStep( "dismiss-item-return-request-validation", @@ -33,12 +91,7 @@ export const dismissItemReturnRequestValidationStep = createStep( orderChange, orderReturn, items, - }: { - order: Pick - orderReturn: ReturnDTO - orderChange: OrderChangeDTO - items: OrderWorkflow.ReceiveOrderReturnItemsWorkflowInput["items"] - }, + }: DismissItemReturnRequestValidationStepInput, context ) { throwIfIsCancelled(order, "Order") @@ -48,14 +101,46 @@ export const dismissItemReturnRequestValidationStep = createStep( } ) +/** + * The data to dismiss items from a return request. + * + * @property return_id - The ID of the return to dismiss items from. + * @property items - The items to dismiss. + */ +export type DismissItemReturnRequestWorkflowInput = OrderWorkflow.ReceiveOrderReturnItemsWorkflowInput + export const dismissItemReturnRequestWorkflowId = "dismiss-item-return-request" /** - * This workflow dismisses items from a return request. + * This workflow dismisses items from a return request due to them being damaged. It's used + * by the [Add Damaged Items Admin API Route](https://docs.medusajs.com/api/admin#returns_postreturnsiddismissitems). + * + * A damaged item's quantity is dismissed, meaning it's not returned to the inventory. + * + * You can use this workflow within your customizations or your own custom workflows, allowing you + * to dismiss items from a return request in your custom flow. + * + * @example + * const { result } = await dismissItemReturnRequestWorkflow(container) + * .run({ + * input: { + * return_id: "return_123", + * items: [ + * { + * id: "orli_123", + * quantity: 1, + * } + * ] + * } + * }) + * + * @summary + * + * Dismiss items from a return request. */ export const dismissItemReturnRequestWorkflow = createWorkflow( dismissItemReturnRequestWorkflowId, function ( - input: WorkflowData + input: WorkflowData ): WorkflowResponse { const orderReturn: ReturnDTO = useRemoteQueryStep({ entry_point: "return", diff --git a/packages/core/core-flows/src/order/workflows/return/receive-complete-return.ts b/packages/core/core-flows/src/order/workflows/return/receive-complete-return.ts index dee40193f1486..db90fa0770c21 100644 --- a/packages/core/core-flows/src/order/workflows/return/receive-complete-return.ts +++ b/packages/core/core-flows/src/order/workflows/return/receive-complete-return.ts @@ -14,8 +14,47 @@ import { throwIfItemsDoesNotExistsInReturn, } from "../../utils/order-validation" +/** + * The data to validate that a return can be received and completed. + */ +export type ReceiveCompleteReturnValidationStepInput = { + /** + * The return's details. + */ + orderReturn: ReturnDTO + /** + * The details of receiving and completing the return. + */ + input: OrderWorkflow.ReceiveCompleteOrderReturnWorkflowInput +} + /** * This step validates that a return can be received and completed. + * If the return is canceled or the items do not exist in the return, the step will throw an error. + * + * :::note + * + * You can retrieve a return details using [Query](https://docs.medusajs.com/learn/fundamentals/module-links/query), + * or [useQueryGraphStep](https://docs.medusajs.com/resources/references/medusa-workflows/steps/useQueryGraphStep). + * + * ::: + * + * @example + * const data = receiveCompleteReturnValidationStep({ + * orderReturn: { + * id: "return_123", + * // other return details... + * }, + * input: { + * return_id: "return_123", + * items: [ + * { + * id: "orli_123", + * quantity: 1, + * } + * ] + * } + * }) */ export const receiveCompleteReturnValidationStep = createStep( "receive-return-order-validation", @@ -23,10 +62,7 @@ export const receiveCompleteReturnValidationStep = createStep( { orderReturn, input, - }: { - orderReturn - input: OrderWorkflow.ReceiveCompleteOrderReturnWorkflowInput - }, + }: ReceiveCompleteReturnValidationStepInput, context ) { throwIfIsCancelled(orderReturn, "Return") @@ -37,6 +73,27 @@ export const receiveCompleteReturnValidationStep = createStep( export const receiveAndCompleteReturnOrderWorkflowId = "receive-return-order" /** * This workflow marks a return as received and completes it. + * + * You can use this workflow within your customizations or your own custom workflows, allowing you + * to receive and complete a return. + * + * @example + * const { result } = await receiveAndCompleteReturnOrderWorkflow(container) + * .run({ + * input: { + * return_id: "return_123", + * items: [ + * { + * id: "orli_123", + * quantity: 1, + * } + * ] + * } + * }) + * + * @summary + * + * Receive and complete a return. */ export const receiveAndCompleteReturnOrderWorkflow = createWorkflow( receiveAndCompleteReturnOrderWorkflowId, diff --git a/packages/core/core-flows/src/order/workflows/return/receive-item-return-request.ts b/packages/core/core-flows/src/order/workflows/return/receive-item-return-request.ts index 888fe754729bb..b08b70671c61d 100644 --- a/packages/core/core-flows/src/order/workflows/return/receive-item-return-request.ts +++ b/packages/core/core-flows/src/order/workflows/return/receive-item-return-request.ts @@ -22,8 +22,61 @@ import { } from "../../utils/order-validation" import { createOrderChangeActionsWorkflow } from "../create-order-change-actions" +/** + * The data to validate that a return's items can be marked as received. + */ +export type ReceiveItemReturnRequestValidationStepInput = { + /** + * The order's details. + */ + order: Pick + /** + * The return's details. + */ + orderReturn: ReturnDTO + /** + * The order change's details. + */ + orderChange: OrderChangeDTO + /** + * The received items. + */ + items: OrderWorkflow.ReceiveOrderReturnItemsWorkflowInput["items"] +} + /** * This step validates that a return's items can be marked as received. + * If the order or return is canceled, the order change is not active, + * or the items do not exist in the return, the step will throw an error. + * + * :::note + * + * You can retrieve an order, return, and order change details using [Query](https://docs.medusajs.com/learn/fundamentals/module-links/query), + * or [useQueryGraphStep](https://docs.medusajs.com/resources/references/medusa-workflows/steps/useQueryGraphStep). + * + * ::: + * + * @example + * const data = receiveItemReturnRequestValidationStep({ + * order: { + * id: "order_123", + * // other order details... + * }, + * orderChange: { + * id: "orch_123", + * // other order change details... + * }, + * orderReturn: { + * id: "return_123", + * // other return details... + * }, + * items: [ + * { + * id: "orli_123", + * quantity: 1, + * } + * ] + * }) */ export const receiveItemReturnRequestValidationStep = createStep( "receive-item-return-request-validation", @@ -33,12 +86,7 @@ export const receiveItemReturnRequestValidationStep = createStep( orderChange, orderReturn, items, - }: { - order: Pick - orderReturn: ReturnDTO - orderChange: OrderChangeDTO - items: OrderWorkflow.ReceiveOrderReturnItemsWorkflowInput["items"] - }, + }: ReceiveItemReturnRequestValidationStepInput, context ) { throwIfIsCancelled(order, "Order") @@ -50,7 +98,29 @@ export const receiveItemReturnRequestValidationStep = createStep( export const receiveItemReturnRequestWorkflowId = "receive-item-return-request" /** - * This workflow marks return items as received. + * This workflow marks return items as received. It's used by the + * [Add Received Items to Return Admin API Route](https://docs.medusajs.com/api/admin#returns_postreturnsidreceiveitems). + * + * You can use this workflow within your customizations or your own custom workflows, allowing you to mark return items as received + * in your custom flows. + * + * @example + * const { result } = await receiveItemReturnRequestWorkflow(container) + * .run({ + * input: { + * return_id: "return_123", + * items: [ + * { + * id: "orli_123", + * quantity: 1, + * } + * ] + * } + * }) + * + * @summary + * + * Mark return items as received. */ export const receiveItemReturnRequestWorkflow = createWorkflow( receiveItemReturnRequestWorkflowId, diff --git a/packages/core/core-flows/src/order/workflows/return/remove-item-receive-return-action.ts b/packages/core/core-flows/src/order/workflows/return/remove-item-receive-return-action.ts index c7bf6b806eb01..e75332a10032e 100644 --- a/packages/core/core-flows/src/order/workflows/return/remove-item-receive-return-action.ts +++ b/packages/core/core-flows/src/order/workflows/return/remove-item-receive-return-action.ts @@ -23,8 +23,60 @@ import { throwIfOrderChangeIsNotActive, } from "../../utils/order-validation" +/** + * The data to validate that a return receival's item can be removed. + */ +export type RemoveItemReceiveReturnActionValidationStepInput = { + /** + * The order's details. + */ + order: OrderDTO + /** + * The return's details. + */ + orderReturn: ReturnDTO + /** + * The order change's details. + */ + orderChange: OrderChangeDTO + /** + * The details of the item to be removed. + */ + input: OrderWorkflow.DeleteRequestItemReceiveReturnWorkflowInput +} + /** * This step validates that a return receival's item can be removed. + * If the order or return is canceled, the order change is not active, + * the return request is not found, + * or the action is not a receive return action, the step will throw an error. + * + * :::note + * + * You can retrieve an order, return, and order change details using [Query](https://docs.medusajs.com/learn/fundamentals/module-links/query), + * or [useQueryGraphStep](https://docs.medusajs.com/resources/references/medusa-workflows/steps/useQueryGraphStep). + * + * ::: + * + * @example + * const data = removeItemReceiveReturnActionValidationStep({ + * order: { + * id: "order_123", + * // other order details... + * }, + * orderChange: { + * id: "orch_123", + * // other order change details... + * }, + * orderReturn: { + * id: "return_123", + * // other return details... + * }, + * input: { + * return_id: "return_123", + * action_id: "orchac_123", + * } + * }) */ export const removeItemReceiveReturnActionValidationStep = createStep( "remove-item-receive-return-action-validation", @@ -33,12 +85,7 @@ export const removeItemReceiveReturnActionValidationStep = createStep( orderChange, orderReturn, input, - }: { - order: OrderDTO - orderReturn: ReturnDTO - orderChange: OrderChangeDTO - input: OrderWorkflow.DeleteRequestItemReceiveReturnWorkflowInput - }) { + }: RemoveItemReceiveReturnActionValidationStepInput) { throwIfIsCancelled(order, "Order") throwIfIsCancelled(orderReturn, "Return") throwIfOrderChangeIsNotActive({ orderChange }) @@ -67,7 +114,24 @@ export const removeItemReceiveReturnActionValidationStep = createStep( export const removeItemReceiveReturnActionWorkflowId = "remove-item-receive-return-action" /** - * This workflow removes an item from a return receival. + * This workflow removes an item from a return receival. It's used by the + * [Remove a Received Item from Return Admin API Route](https://docs.medusajs.com/api/admin#returns_deletereturnsidreceiveitemsaction_id). + * + * You can use this workflow within your customizations or your own custom workflows, allowing you to remove an item from a return receival + * in your custom flow. + * + * @example + * const { result } = await removeItemReceiveReturnActionWorkflow(container) + * .run({ + * input: { + * return_id: "return_123", + * action_id: "orchac_123", + * } + * }) + * + * @summary + * + * Remove an item from a return receival. */ export const removeItemReceiveReturnActionWorkflow = createWorkflow( removeItemReceiveReturnActionWorkflowId, diff --git a/packages/core/core-flows/src/order/workflows/return/remove-item-return-action.ts b/packages/core/core-flows/src/order/workflows/return/remove-item-return-action.ts index 0ffb7bff3400a..339b1c90632f9 100644 --- a/packages/core/core-flows/src/order/workflows/return/remove-item-return-action.ts +++ b/packages/core/core-flows/src/order/workflows/return/remove-item-return-action.ts @@ -27,8 +27,60 @@ import { import { removeReturnShippingMethodWorkflow } from "./remove-return-shipping-method" import { updateReturnWorkflow } from "./update-return" +/** + * The data to validate that a return item can be removed. + */ +export type RemoveItemReturnActionValidationStepInput = { + /** + * The order's details. + */ + order: OrderDTO + /** + * The return's details. + */ + orderReturn: ReturnDTO + /** + * The order change's details. + */ + orderChange: OrderChangeDTO + /** + * The details of the item to be removed. + */ + input: OrderWorkflow.DeleteRequestItemReturnWorkflowInput +} + /** * This step validates that a return item can be removed. + * If the order or return is canceled, the order change is not active, + * the return request is not found, + * or the action is not a request return action, the step will throw an error. + * + * :::note + * + * You can retrieve an order, return, and order change details using [Query](https://docs.medusajs.com/learn/fundamentals/module-links/query), + * or [useQueryGraphStep](https://docs.medusajs.com/resources/references/medusa-workflows/steps/useQueryGraphStep). + * + * ::: + * + * @example + * const data = removeReturnItemActionValidationStep({ + * order: { + * id: "order_123", + * // other order details... + * }, + * orderChange: { + * id: "orch_123", + * // other order change details... + * }, + * orderReturn: { + * id: "return_123", + * // other return details... + * }, + * input: { + * return_id: "return_123", + * action_id: "orchac_123", + * } + * }) */ export const removeReturnItemActionValidationStep = createStep( "remove-item-return-action-validation", @@ -37,12 +89,7 @@ export const removeReturnItemActionValidationStep = createStep( orderChange, orderReturn, input, - }: { - order: OrderDTO - orderReturn: ReturnDTO - orderChange: OrderChangeDTO - input: OrderWorkflow.DeleteRequestItemReturnWorkflowInput - }) { + }: RemoveItemReturnActionValidationStepInput) { throwIfIsCancelled(order, "Order") throwIfIsCancelled(orderReturn, "Return") throwIfOrderChangeIsNotActive({ orderChange }) @@ -65,7 +112,24 @@ export const removeReturnItemActionValidationStep = createStep( export const removeItemReturnActionWorkflowId = "remove-item-return-action" /** - * This workflow removes a return item. + * This workflow removes a return item. It's used by the + * [Remove Item from Return Admin API Route](https://docs.medusajs.com/api/admin#returns_deletereturnsidrequestitemsaction_id). + * + * You can use this workflow within your customizations or your own custom workflows, allowing you + * to remove an item from a return request in your custom flows. + * + * @example + * const { result } = await removeItemReturnActionWorkflow(container) + * .run({ + * input: { + * return_id: "return_123", + * action_id: "orchac_123", + * } + * }) + * + * @summary + * + * Remove an item from a return. */ export const removeItemReturnActionWorkflow = createWorkflow( removeItemReturnActionWorkflowId, diff --git a/packages/core/core-flows/src/order/workflows/return/remove-return-shipping-method.ts b/packages/core/core-flows/src/order/workflows/return/remove-return-shipping-method.ts index 47bd17f60130c..975ca35d3878a 100644 --- a/packages/core/core-flows/src/order/workflows/return/remove-return-shipping-method.ts +++ b/packages/core/core-flows/src/order/workflows/return/remove-return-shipping-method.ts @@ -23,8 +23,52 @@ import { throwIfOrderChangeIsNotActive, } from "../../utils/order-validation" +/** + * The data to validate that a shipping method can be removed from a return. + */ +export type RemoveReturnShippingMethodValidationStepInput = { + /** + * The order change's details. + */ + orderChange: OrderChangeDTO + /** + * The return's details. + */ + orderReturn: ReturnDTO + /** + * The details of the shipping method to be removed. + */ + input: Pick +} + /** * This step validates that a shipping method can be removed from a return. + * If the return is canceled, the order change is not active, + * the shipping method isn't in the return, + * or the action doesn't add a shipping method, the step will throw an error. + * + * :::note + * + * You can retrieve a return and order change details using [Query](https://docs.medusajs.com/learn/fundamentals/module-links/query), + * or [useQueryGraphStep](https://docs.medusajs.com/resources/references/medusa-workflows/steps/useQueryGraphStep). + * + * ::: + * + * @example + * const data = removeReturnShippingMethodValidationStep({ + * orderChange: { + * id: "orch_123", + * // other order change details... + * }, + * orderReturn: { + * id: "return_123", + * // other return details... + * }, + * input: { + * return_id: "return_123", + * action_id: "orchac_123", + * } + * }) */ export const removeReturnShippingMethodValidationStep = createStep( "validate-remove-return-shipping-method", @@ -32,11 +76,7 @@ export const removeReturnShippingMethodValidationStep = createStep( orderChange, orderReturn, input, - }: { - input: { return_id: string; action_id: string } - orderReturn: ReturnDTO - orderChange: OrderChangeDTO - }) { + }: RemoveReturnShippingMethodValidationStepInput) { throwIfIsCancelled(orderReturn, "Return") throwIfOrderChangeIsNotActive({ orderChange }) @@ -59,7 +99,24 @@ export const removeReturnShippingMethodValidationStep = createStep( export const removeReturnShippingMethodWorkflowId = "remove-return-shipping-method" /** - * This workflow removes a shipping method from a return. + * This workflow removes a shipping method from a return. It's used by the + * [Remove Shipping Method from Return Admin API Route](https://docs.medusajs.com/api/admin#returns_deletereturnsidshippingmethodaction_id). + * + * You can use this workflow within your customizations or your own custom workflows, allowing you + * to remove a shipping method from a return in your custom flows. + * + * @example + * const { result } = await removeReturnShippingMethodWorkflow(container) + * .run({ + * input: { + * return_id: "return_123", + * action_id: "orchac_123", + * } + * }) + * + * @summary + * + * Remove a shipping method from a return. */ export const removeReturnShippingMethodWorkflow = createWorkflow( removeReturnShippingMethodWorkflowId, diff --git a/packages/core/core-flows/src/order/workflows/return/request-item-return.ts b/packages/core/core-flows/src/order/workflows/return/request-item-return.ts index abd47d1543f90..f6ce9ecf78df6 100644 --- a/packages/core/core-flows/src/order/workflows/return/request-item-return.ts +++ b/packages/core/core-flows/src/order/workflows/return/request-item-return.ts @@ -24,7 +24,66 @@ import { validateReturnReasons } from "../../utils/validate-return-reason" import { createOrderChangeActionsWorkflow } from "../create-order-change-actions" /** - * This step validates that itens can be added to a return. + * The data to validate that items can be added to a return. + */ +export type RequestItemReturnValidationStepInput = { + /** + * The order's details. + */ + order: Pick + /** + * The return's details. + */ + orderReturn: ReturnDTO + /** + * The order change's details. + */ + orderChange: OrderChangeDTO + /** + * The items to be added to the return. + */ + items: OrderWorkflow.RequestItemReturnWorkflowInput["items"] +} + +/** + * This step validates that items can be added to a return. + * If the order or return is canceled, the order change is not active, + * the items do not exist in the order, or the return reasons are invalid, + * the step will throw an error. + * + * :::note + * + * You can retrieve an order, return, and order change details using [Query](https://docs.medusajs.com/learn/fundamentals/module-links/query), + * or [useQueryGraphStep](https://docs.medusajs.com/resources/references/medusa-workflows/steps/useQueryGraphStep). + * + * ::: + * + * @example + * const data = requestItemReturnValidationStep({ + * order: { + * id: "order_123", + * items: [ + * { + * id: "orli_123", + * // other item details... + * } + * ] + * }, + * orderChange: { + * id: "orch_123", + * // other order change details... + * }, + * orderReturn: { + * id: "return_123", + * // other return details... + * }, + * items: [ + * { + * id: "orli_123", + * quantity: 1, + * } + * ] + * }) */ export const requestItemReturnValidationStep = createStep( "request-item-return-validation", @@ -34,12 +93,7 @@ export const requestItemReturnValidationStep = createStep( orderChange, orderReturn, items, - }: { - order: Pick - orderReturn: ReturnDTO - orderChange: OrderChangeDTO - items: OrderWorkflow.RequestItemReturnWorkflowInput["items"] - }, + }: RequestItemReturnValidationStepInput, context ) { throwIfIsCancelled(order, "Order") @@ -56,7 +110,29 @@ export const requestItemReturnValidationStep = createStep( export const requestItemReturnWorkflowId = "request-item-return" /** - * This workflow adds items to a return. + * This workflow adds items to a return. It's used by the + * [Add Requested Items to Return Admin API Route](https://docs.medusajs.com/api/admin#returns_postreturnsidrequestitems). + * + * You can use this workflow within your customizations or your own custom workflows, allowing you to add items to a return + * in your custom flows. + * + * @example + * const { result } = await requestItemReturnWorkflow(container) + * .run({ + * input: { + * return_id: "return_123", + * items: [ + * { + * id: "orli_123", + * quantity: 1, + * } + * ] + * } + * }) + * + * @summary + * + * Add items to a return. */ export const requestItemReturnWorkflow = createWorkflow( requestItemReturnWorkflowId, diff --git a/packages/core/core-flows/src/order/workflows/return/update-receive-item-return-request.ts b/packages/core/core-flows/src/order/workflows/return/update-receive-item-return-request.ts index 5087cbef4fcb3..33e49ee4fb0f6 100644 --- a/packages/core/core-flows/src/order/workflows/return/update-receive-item-return-request.ts +++ b/packages/core/core-flows/src/order/workflows/return/update-receive-item-return-request.ts @@ -24,8 +24,68 @@ import { throwIfOrderChangeIsNotActive, } from "../../utils/order-validation" +/** + * The data to validate that an item can be updated in a return receival request. + */ +export type UpdateReceiveItemReturnRequestValidationStepInput = { + /** + * The order's details. + */ + order: OrderDTO + /** + * The return's details. + */ + orderReturn: ReturnDTO + /** + * The order change's details. + */ + orderChange: OrderChangeDTO + /** + * The details of the item update. + */ + input: OrderWorkflow.UpdateReceiveItemReturnRequestWorkflowInput +} + /** * This step validates that an item can be updated in a return receival request. + * If the order or return is canceled, the order change is not active, + * the return request is not found, or the action is not receiving an item return request, + * the step will throw an error. + * + * :::note + * + * You can retrieve an order, return, and order change details using [Query](https://docs.medusajs.com/learn/fundamentals/module-links/query), + * or [useQueryGraphStep](https://docs.medusajs.com/resources/references/medusa-workflows/steps/useQueryGraphStep). + * + * ::: + * + * @example + * const data = updateReceiveItemReturnRequestValidationStep({ + * order: { + * id: "order_123", + * items: [ + * { + * id: "orli_123", + * // other item details... + * } + * ] + * }, + * orderChange: { + * id: "orch_123", + * // other order change details... + * }, + * orderReturn: { + * id: "return_123", + * // other return details... + * }, + * input: { + * return_id: "return_123", + * action_id: "orchac_123", + * data: { + * quantity: 1, + * } + * } + * }) */ export const updateReceiveItemReturnRequestValidationStep = createStep( "update-receive-item-return-request-validation", @@ -35,12 +95,7 @@ export const updateReceiveItemReturnRequestValidationStep = createStep( orderChange, orderReturn, input, - }: { - order: OrderDTO - orderReturn: ReturnDTO - orderChange: OrderChangeDTO - input: OrderWorkflow.UpdateReceiveItemReturnRequestWorkflowInput - }, + }: UpdateReceiveItemReturnRequestValidationStepInput, context ) { throwIfIsCancelled(order, "Order") @@ -71,7 +126,27 @@ export const updateReceiveItemReturnRequestValidationStep = createStep( export const updateReceiveItemReturnRequestWorkflowId = "update-receive-item-return-request" /** - * This workflow updates an item in a return receival request. + * This workflow updates an item in a return receival request. It's used by the + * [Update a Received Item in a Return Admin API Route](https://docs.medusajs.com/api/admin#returns_postreturnsidreceiveitemsaction_id). + * + * You can use this workflow within your customizations or your own custom workflows, allowing you to update an item in a return receival request + * in your custom flows. + * + * @example + * const { result } = await updateReceiveItemReturnRequestWorkflow(container) + * .run({ + * input: { + * return_id: "return_123", + * action_id: "orchac_123", + * data: { + * quantity: 1, + * } + * } + * }) + * + * @summary + * + * Update an item in a return receival request. */ export const updateReceiveItemReturnRequestWorkflow = createWorkflow( updateReceiveItemReturnRequestWorkflowId, diff --git a/packages/core/core-flows/src/order/workflows/return/update-request-item-return.ts b/packages/core/core-flows/src/order/workflows/return/update-request-item-return.ts index b320beb98bf53..543d88d89868b 100644 --- a/packages/core/core-flows/src/order/workflows/return/update-request-item-return.ts +++ b/packages/core/core-flows/src/order/workflows/return/update-request-item-return.ts @@ -29,8 +29,63 @@ import { } from "../../utils/order-validation" import { validateReturnReasons } from "../../utils/validate-return-reason" +/** + * The data to validate that an item in a return can be updated. + */ +export type UpdateRequestItemReturnValidationStepInput = { + /** + * The order's details. + */ + order: OrderDTO + /** + * The return's details. + */ + orderReturn: ReturnDTO + /** + * The order change's details. + */ + orderChange: OrderChangeDTO + /** + * The details of updating the item. + */ + input: OrderWorkflow.UpdateRequestItemReturnWorkflowInput +} + /** * This step validates that an item in a return can be updated. + * If the order or return is canceled, the order change is not active, + * the return request is not found, or the action is not requesting an item return, + * the step will throw an error. + * + * :::note + * + * You can retrieve an order, return, and order change details using [Query](https://docs.medusajs.com/learn/fundamentals/module-links/query), + * or [useQueryGraphStep](https://docs.medusajs.com/resources/references/medusa-workflows/steps/useQueryGraphStep). + * + * ::: + * + * @example + * const data = updateRequestItemReturnValidationStep({ + * order: { + * id: "order_123", + * // other order details... + * }, + * orderChange: { + * id: "orch_123", + * // other order change details... + * }, + * orderReturn: { + * id: "return_123", + * // other return details... + * }, + * input: { + * return_id: "return_123", + * action_id: "orchac_123", + * data: { + * quantity: 1, + * } + * } + * }) */ export const updateRequestItemReturnValidationStep = createStep( "update-request-item-return-validation", @@ -40,12 +95,7 @@ export const updateRequestItemReturnValidationStep = createStep( orderChange, orderReturn, input, - }: { - order: OrderDTO - orderReturn: ReturnDTO - orderChange: OrderChangeDTO - input: OrderWorkflow.UpdateRequestItemReturnWorkflowInput - }, + }: UpdateRequestItemReturnValidationStepInput, context ) { throwIfIsCancelled(order, "Order") @@ -80,7 +130,27 @@ export const updateRequestItemReturnValidationStep = createStep( export const updateRequestItemReturnWorkflowId = "update-request-item-return" /** - * This workflow updates an item in a return. + * This workflow updates a requested item in a return. It's used by the + * [Update Requested Item in Return Admin API Route](https://docs.medusajs.com/api/admin#returns_postreturnsidrequestitemsaction_id). + * + * You can use this workflow within your customizations or your own custom workflows, allowing you to update an + * item in a return in your custom flows. + * + * @example + * const { result } = await updateRequestItemReturnWorkflow(container) + * .run({ + * input: { + * return_id: "return_123", + * action_id: "orchac_123", + * data: { + * quantity: 1, + * } + * } + * }) + * + * @summary + * + * Update a requested item in a return. */ export const updateRequestItemReturnWorkflow = createWorkflow( updateRequestItemReturnWorkflowId, diff --git a/packages/core/core-flows/src/order/workflows/return/update-return-shipping-method.ts b/packages/core/core-flows/src/order/workflows/return/update-return-shipping-method.ts index 6a14d16b34d8f..0069ffcb23bec 100644 --- a/packages/core/core-flows/src/order/workflows/return/update-return-shipping-method.ts +++ b/packages/core/core-flows/src/order/workflows/return/update-return-shipping-method.ts @@ -27,8 +27,52 @@ import { } from "../../utils/order-validation" import { prepareShippingMethodUpdate } from "../../utils/prepare-shipping-method" +/** + * The data to validate that a return's shipping method can be updated. + */ +export type UpdateReturnShippingMethodValidationStepInput = { + /** + * The order change's details. + */ + orderChange: OrderChangeDTO + /** + * The return's details. + */ + orderReturn: ReturnDTO + /** + * The details of updating the shipping method. + */ + input: Pick +} + /** * This step validates that a return's shipping method can be updated. + * If the return is canceled, the order change is not active, + * the shipping method isn't in the return, or the action isn't adding a shipping method, + * the step will throw an error. + * + * :::note + * + * You can retrieve a return and order change details using [Query](https://docs.medusajs.com/learn/fundamentals/module-links/query), + * or [useQueryGraphStep](https://docs.medusajs.com/resources/references/medusa-workflows/steps/useQueryGraphStep). + * + * ::: + * + * @example + * const data = updateReturnShippingMethodValidationStep({ + * orderChange: { + * id: "orch_123", + * // other order change details... + * }, + * orderReturn: { + * id: "return_123", + * // other return details... + * }, + * input: { + * return_id: "return_123", + * action_id: "orchac_123", + * } + * }) */ export const updateReturnShippingMethodValidationStep = createStep( "validate-update-return-shipping-method", @@ -36,11 +80,7 @@ export const updateReturnShippingMethodValidationStep = createStep( orderChange, orderReturn, input, - }: { - input: { return_id: string; action_id: string } - orderReturn: ReturnDTO - orderChange: OrderChangeDTO - }) { + }: UpdateReturnShippingMethodValidationStepInput) { throwIfIsCancelled(orderReturn, "Return") throwIfOrderChangeIsNotActive({ orderChange }) @@ -63,7 +103,27 @@ export const updateReturnShippingMethodValidationStep = createStep( export const updateReturnShippingMethodWorkflowId = "update-return-shipping-method" /** - * This workflow updates the shipping method of a return. + * This workflow updates the shipping method of a return. It's used by the + * [Update Shipping Method Admin API Route](https://docs.medusajs.com/api/admin#returns_postreturnsidshippingmethodaction_id). + * + * You can use this workflow within your customizations or your own custom workflows, allowing you + * to update the shipping method of a return in your custom flows. + * + * @example + * const { result } = await updateReturnShippingMethodWorkflow(container) + * .run({ + * input: { + * return_id: "return_123", + * action_id: "orchac_123", + * data: { + * custom_amount: 10, + * } + * } + * }) + * + * @summary + * + * Update the shipping method of a return. */ export const updateReturnShippingMethodWorkflow = createWorkflow( updateReturnShippingMethodWorkflowId, diff --git a/packages/core/core-flows/src/order/workflows/return/update-return.ts b/packages/core/core-flows/src/order/workflows/return/update-return.ts index 8d6ed155bcd04..f8cebe3da56f4 100644 --- a/packages/core/core-flows/src/order/workflows/return/update-return.ts +++ b/packages/core/core-flows/src/order/workflows/return/update-return.ts @@ -21,17 +21,48 @@ import { } from "../../utils/order-validation" /** - * This step validates that a return can be updated + * The data to validate that a return can be updated. + */ +export type UpdateReturnValidationStepInput = { + /** + * The order change's details. + */ + orderChange: OrderChangeDTO + /** + * The return's details. + */ + orderReturn: ReturnDTO +} + +/** + * This step validates that a return can be updated. + * If the return is canceled or the order change is not active, the step will throw an error. + * + * :::note + * + * You can retrieve a return and order change details using [Query](https://docs.medusajs.com/learn/fundamentals/module-links/query), + * or [useQueryGraphStep](https://docs.medusajs.com/resources/references/medusa-workflows/steps/useQueryGraphStep). + * + * ::: + * + * @example + * const data = updateReturnValidationStep({ + * orderChange: { + * id: "orch_123", + * // other order change details... + * }, + * orderReturn: { + * id: "return_123", + * // other return details... + * }, + * }) */ export const updateReturnValidationStep = createStep( "validate-update-return", async function ({ orderChange, orderReturn, - }: { - orderReturn: ReturnDTO - orderChange: OrderChangeDTO - }) { + }: UpdateReturnValidationStepInput) { throwIfIsCancelled(orderReturn, "Return") throwIfOrderChangeIsNotActive({ orderChange }) } @@ -39,7 +70,24 @@ export const updateReturnValidationStep = createStep( export const updateReturnWorkflowId = "update-return" /** - * This workflow updates a return. + * This workflow updates a return's details. It's used by the + * [Update Return Admin API Route](https://docs.medusajs.com/api/admin#returns_postreturnsid). + * + * You can use this workflow within your customizations or your own custom workflows, allowing you + * to update a return in your custom flow. + * + * @example + * const { result } = await updateReturnWorkflow(container) + * .run({ + * input: { + * return_id: "return_123", + * no_notification: true + * } + * }) + * + * @summary + * + * Update a return's details. */ export const updateReturnWorkflow = createWorkflow( updateReturnWorkflowId, diff --git a/packages/core/core-flows/src/order/workflows/transfer/accept-order-transfer.ts b/packages/core/core-flows/src/order/workflows/transfer/accept-order-transfer.ts index a48e4a22e4757..b3ba57d1089d3 100644 --- a/packages/core/core-flows/src/order/workflows/transfer/accept-order-transfer.ts +++ b/packages/core/core-flows/src/order/workflows/transfer/accept-order-transfer.ts @@ -23,7 +23,46 @@ import { previewOrderChangeStep } from "../../steps" import { confirmOrderChanges } from "../../steps/confirm-order-changes" /** - * This step validates that an order transfer can be accepted. + * The details of the order transfer acceptance to validate. + */ +export type AcceptOrderTransferValidationStepInput = { + /** + * The token of the order transfer. + */ + token: string + /** + * The order to accept the transfer for. + */ + order: OrderDTO + /** + * The order change made by the transfer request. + */ + orderChange: OrderChangeDTO +} + +/** + * This step validates that an order transfer can be accepted. If the + * order doesn't have an existing transfer request, the step throws an error. + * + * :::note + * + * You can retrieve an order and order change details using [Query](https://docs.medusajs.com/learn/fundamentals/module-links/query), + * or [useQueryGraphStep](https://docs.medusajs.com/resources/references/medusa-workflows/steps/useQueryGraphStep). + * + * ::: + * + * @example + * const data = acceptOrderTransferValidationStep({ + * token: "sk_123456", + * order: { + * id: "order_123", + * // other order details... + * }, + * orderChange: { + * id: "order_change_123", + * // other order change details... + * } + * }) */ export const acceptOrderTransferValidationStep = createStep( "accept-order-transfer-validation", @@ -56,7 +95,24 @@ export const acceptOrderTransferValidationStep = createStep( export const acceptOrderTransferWorkflowId = "accept-order-transfer-workflow" /** - * This workflow accepts an order transfer. + * This workflow accepts an order transfer, requested previously by the {@link requestOrderTransferWorkflow}. This workflow is used by the + * [Accept Order Transfer Store API Route](https://docs.medusajs.com/api/store#orders_postordersidtransferaccept). + * + * You can use this workflow within your customizations or your own custom workflows, allowing you to build a custom flow + * around accepting an order transfer. + * + * @example + * const { result } = await acceptOrderTransferWorkflow(container) + * .run({ + * input: { + * token: "sk_123456", + * order_id: "order_123", + * } + * }) + * + * @summary + * + * Accept an order transfer request. */ export const acceptOrderTransferWorkflow = createWorkflow( acceptOrderTransferWorkflowId, diff --git a/packages/core/core-flows/src/order/workflows/transfer/cancel-order-transfer.ts b/packages/core/core-flows/src/order/workflows/transfer/cancel-order-transfer.ts index 4044e0a866a19..76a20f1c5a92f 100644 --- a/packages/core/core-flows/src/order/workflows/transfer/cancel-order-transfer.ts +++ b/packages/core/core-flows/src/order/workflows/transfer/cancel-order-transfer.ts @@ -21,8 +21,52 @@ import { throwIfOrderChangeIsNotActive, } from "../../utils/order-validation" +/** + * The details of the order transfer cancellation to validate. + */ +export type CancelTransferOrderRequestValidationStep = { + /** + * The order to cancel the transfer request for. + */ + order: OrderDTO + /** + * The order change made by the transfer request. + */ + orderChange: OrderChangeDTO + /** + * The cancelation details. + */ + input: OrderWorkflow.CancelTransferOrderRequestWorkflowInput +} + /** * This step validates that a requested order transfer can be canceled. + * If the customer canceling the order transfer isn't the one that requested the transfer, + * the step throws an error. Admin users can cancel any order transfer. + * + * :::note + * + * You can retrieve an order and order change details using [Query](https://docs.medusajs.com/learn/fundamentals/module-links/query), + * or [useQueryGraphStep](https://docs.medusajs.com/resources/references/medusa-workflows/steps/useQueryGraphStep). + * + * ::: + * + * @example + * const data = cancelTransferOrderRequestValidationStep({ + * order: { + * id: "order_123", + * // other order details... + * }, + * orderChange: { + * id: "order_change_123", + * // other order change details... + * }, + * input: { + * order_id: "order_123", + * logged_in_user_id: "cus_123", + * actor_type: "customer" + * } + * }) */ export const cancelTransferOrderRequestValidationStep = createStep( "validate-cancel-transfer-order-request", @@ -30,11 +74,7 @@ export const cancelTransferOrderRequestValidationStep = createStep( order, orderChange, input, - }: { - order: OrderDTO - orderChange: OrderChangeDTO - input: OrderWorkflow.CancelTransferOrderRequestWorkflowInput - }) { + }: CancelTransferOrderRequestValidationStep) { throwIfIsCancelled(order, "Order") throwIfOrderChangeIsNotActive({ orderChange }) @@ -58,9 +98,26 @@ export const cancelTransferOrderRequestValidationStep = createStep( export const cancelTransferOrderRequestWorkflowId = "cancel-transfer-order-request" /** - * This workflow cancels a requested order transfer. - * - * Customer that requested the transfer or a store admin are allowed to cancel the order transfer request. + * This workflow cancels a requested order transfer. This operation is allowed only by admin users and the customer that requested the transfer. + * This workflow is used by the [Cancel Order Transfer Store API Route](https://docs.medusajs.com/api/store#orders_postordersidtransfercancel), + * and the [Cancel Transfer Request Admin API Route](https://docs.medusajs.com/api/admin#orders_postordersidtransfercancel). + * + * You can use this workflow within your customizations or your own custom workflows, allowing you to build a custom flow + * around canceling an order transfer. + * + * @example + * const { result } = await cancelOrderTransferRequestWorkflow(container) + * .run({ + * input: { + * order_id: "order_123", + * logged_in_user_id: "cus_123", + * actor_type: "customer" + * } + * }) + * + * @summary + * + * Cancel an order transfer request. */ export const cancelOrderTransferRequestWorkflow = createWorkflow( cancelTransferOrderRequestWorkflowId, diff --git a/packages/core/core-flows/src/order/workflows/transfer/decline-order-transfer.ts b/packages/core/core-flows/src/order/workflows/transfer/decline-order-transfer.ts index bc48192d05faf..a342b7d9417f9 100644 --- a/packages/core/core-flows/src/order/workflows/transfer/decline-order-transfer.ts +++ b/packages/core/core-flows/src/order/workflows/transfer/decline-order-transfer.ts @@ -22,8 +22,51 @@ import { throwIfOrderChangeIsNotActive, } from "../../utils/order-validation" +/** + * The details of the order transfer decline to validate. + */ +export type DeclineTransferOrderRequestValidationStepInput = { + /** + * The order to decline the transfer request for. + */ + order: OrderDTO + /** + * The order change made by the transfer request. + */ + orderChange: OrderChangeDTO + /** + * The decline details. + */ + input: OrderWorkflow.DeclineTransferOrderRequestWorkflowInput +} + /** * This step validates that a requested order transfer can be declineed. + * If the provided token doesn't match the token of the transfer request, + * the step throws an error. + * + * :::note + * + * You can retrieve an order and order change details using [Query](https://docs.medusajs.com/learn/fundamentals/module-links/query), + * or [useQueryGraphStep](https://docs.medusajs.com/resources/references/medusa-workflows/steps/useQueryGraphStep). + * + * ::: + * + * @example + * const data = declineTransferOrderRequestValidationStep({ + * order: { + * id: "order_123", + * // other order details... + * }, + * orderChange: { + * id: "order_change_123", + * // other order change details... + * }, + * input: { + * token: "token_123", + * order_id: "order_123", + * } + * }) */ export const declineTransferOrderRequestValidationStep = createStep( "validate-decline-transfer-order-request", @@ -31,11 +74,7 @@ export const declineTransferOrderRequestValidationStep = createStep( order, orderChange, input, - }: { - order: OrderDTO - orderChange: OrderChangeDTO - input: OrderWorkflow.DeclineTransferOrderRequestWorkflowInput - }) { + }: DeclineTransferOrderRequestValidationStepInput) { throwIfIsCancelled(order, "Order") throwIfOrderChangeIsNotActive({ orderChange }) @@ -52,9 +91,23 @@ export const declineTransferOrderRequestValidationStep = createStep( export const declineTransferOrderRequestWorkflowId = "decline-transfer-order-request" /** - * This workflow declines a requested order transfer. - * - * Only the original customer (who has the token) is allowed to decline the transfer. + * This workflow declines a requested order transfer by its token. It's used by the + * [Decline Order Transfer Store API Route](https://docs.medusajs.com/api/store#orders_postordersidtransferdecline). + * + * You can use this workflow within your customizations or your own custom workflows, allowing you to wrap custom logic around declining an order transfer request. + * + * @example + * const { result } = await declineOrderTransferRequestWorkflow(container) + * .run({ + * input: { + * token: "token_123", + * order_id: "order_123", + * } + * }) + * + * @summary + * + * Decline a requested order transfer. */ export const declineOrderTransferRequestWorkflow = createWorkflow( declineTransferOrderRequestWorkflowId, diff --git a/packages/core/core-flows/src/order/workflows/transfer/request-order-transfer.ts b/packages/core/core-flows/src/order/workflows/transfer/request-order-transfer.ts index 55b55998f7eb3..f8794b7f22034 100644 --- a/packages/core/core-flows/src/order/workflows/transfer/request-order-transfer.ts +++ b/packages/core/core-flows/src/order/workflows/transfer/request-order-transfer.ts @@ -22,17 +22,49 @@ import { import { previewOrderChangeStep, updateOrderChangesStep } from "../../steps" /** - * This step validates that an order transfer can be requested. + * The details of the order transfer request to validate. + */ +export type RequestOrderTransferValidationStepInput = { + /** + * The order to transfer. + */ + order: OrderDTO + /** + * The customer to transfer the order to. + */ + customer: CustomerDTO +} + +/** + * This step validates that an order transfer can be requested. If the customer + * is a guest customer, or the order already belongs to a registered customer, + * the step throws an error. + * + * :::note + * + * You can retrieve an order and customer details using [Query](https://docs.medusajs.com/learn/fundamentals/module-links/query), + * or [useQueryGraphStep](https://docs.medusajs.com/resources/references/medusa-workflows/steps/useQueryGraphStep). + * + * ::: + * + * @example + * const data = requestOrderTransferValidationStep({ + * order: { + * id: "order_123", + * // other order details... + * }, + * customer: { + * id: "customer_123", + * // other customer details... + * } + * }) */ export const requestOrderTransferValidationStep = createStep( "request-order-transfer-validation", async function ({ order, customer, - }: { - order: OrderDTO - customer: CustomerDTO - }) { + }: RequestOrderTransferValidationStepInput) { throwIfOrderIsCancelled({ order }) if (!customer.has_account) { @@ -53,10 +85,27 @@ export const requestOrderTransferValidationStep = createStep( export const requestOrderTransferWorkflowId = "request-order-transfer-workflow" /** - * This workflow requests an order transfer. - * - * Can be initiated by a store admin or the customer. - * If customer requested the transfer `input.logged_in_user === input.customer_id`. + * This workflow requests an order transfer from a guest customer to a registered customer. It can be requested by an admin user or a customer. + * If a customer requested the transfer, the `logged_in_user` input property should be the same as the customer's ID. + * + * This workflow is used by the [Request Order Transfer Store API Route](https://docs.medusajs.com/api/store#orders_postordersidtransferrequest), + * and the [Request Order Transfer Admin API Route](https://docs.medusajs.com/api/admin#orders_postordersidtransfer). + * + * You can use this workflow within your customizations or your own custom workflows, allowing you to build a custom flow around requesting an order transfer. + * + * @example + * const { result } = await requestOrderTransferWorkflow(container) + * .run({ + * input: { + * order_id: "order_123", + * customer_id: "customer_123", + * logged_in_user: "user_123", + * } + * }) + * + * @summary + * + * Request a transfer of an order to a customer. */ export const requestOrderTransferWorkflow = createWorkflow( requestOrderTransferWorkflowId, diff --git a/packages/core/core-flows/src/order/workflows/update-order-change-actions.ts b/packages/core/core-flows/src/order/workflows/update-order-change-actions.ts index 39db0b0b7994d..aa32ea384bfee 100644 --- a/packages/core/core-flows/src/order/workflows/update-order-change-actions.ts +++ b/packages/core/core-flows/src/order/workflows/update-order-change-actions.ts @@ -12,6 +12,13 @@ import { updateOrderChangeActionsStep } from "../steps" export const updateOrderChangeActionsWorkflowId = "update-order-change-actions" /** * This workflow updates one or more order change actions. + * + * You can use this workflow within your customizations or your own custom workflows, allowing you to wrap custom logic around + * updating order change actions. + * + * @summary + * + * Update one or more order change actions. */ export const updateOrderChangeActionsWorkflow = createWorkflow( updateOrderChangeActionsWorkflowId, diff --git a/packages/core/core-flows/src/order/workflows/update-order-changes.ts b/packages/core/core-flows/src/order/workflows/update-order-changes.ts index 20a9a22f22912..8c52b6344f676 100644 --- a/packages/core/core-flows/src/order/workflows/update-order-changes.ts +++ b/packages/core/core-flows/src/order/workflows/update-order-changes.ts @@ -12,6 +12,13 @@ import { updateOrderChangesStep } from "../steps" export const updateOrderChangesWorkflowId = "update-order-change" /** * This workflow updates one or more order changes. + * + * You can use this workflow within your customizations or your own custom workflows, allowing you to wrap custom logic around + * updating order changes. + * + * @summary + * + * Update one or more order changes. */ export const updateOrderChangesWorkflow = createWorkflow( updateOrderChangesWorkflowId, diff --git a/packages/core/core-flows/src/order/workflows/update-order.ts b/packages/core/core-flows/src/order/workflows/update-order.ts index b78ac81e9d487..fc036cdf0d800 100644 --- a/packages/core/core-flows/src/order/workflows/update-order.ts +++ b/packages/core/core-flows/src/order/workflows/update-order.ts @@ -26,17 +26,48 @@ import { import { emitEventStep, useQueryGraphStep } from "../../common" /** - * This step validates that an order can be updated with provided input. + * The data to validate the order update. + */ +export type UpdateOrderValidationStepInput = { + /** + * The order to validate the update for. + */ + order: OrderDTO + /** + * The order update details. + */ + input: OrderWorkflow.UpdateOrderWorkflowInput +} + +/** + * This step validates that an order can be updated with provided input. If the order is cancelled, + * the email is invalid, or the country code is being changed in the shipping or billing addresses, the step will throw an error. + * + * :::note + * + * You can retrieve an order's details using [Query](https://docs.medusajs.com/learn/fundamentals/module-links/query), + * or [useQueryGraphStep](https://docs.medusajs.com/resources/references/medusa-workflows/steps/useQueryGraphStep). + * + * ::: + * + * @example + * const data = updateOrderValidationStep({ + * order: { + * id: "order_123", + * // other order details... + * }, + * input: { + * id: "order_123", + * user_id: "user_123" + * } + * }) */ export const updateOrderValidationStep = createStep( "update-order-validation", async function ({ order, input, - }: { - order: OrderDTO - input: OrderWorkflow.UpdateOrderWorkflowInput - }) { + }: UpdateOrderValidationStepInput) { throwIfOrderIsCancelled({ order }) if ( @@ -69,7 +100,25 @@ export const updateOrderValidationStep = createStep( export const updateOrderWorkflowId = "update-order-workflow" /** - * Update order workflow. + * This workflow updates an order's general details, such as its email or addresses. It's used by the + * [Update Order Admin API Route](https://docs.medusajs.com/api/admin#orders_postordersid). + * + * You can use this workflow within your customizations or your own custom workflows, allowing you to update an + * order's details in your custom flows. + * + * @example + * const { result } = await updateOrderWorkflow(container) + * .run({ + * input: { + * id: "order_123", + * user_id: "user_123", + * email: "example@gmail.com", + * } + * }) + * + * @summary + * + * Update an order's details. */ export const updateOrderWorkflow = createWorkflow( updateOrderWorkflowId, diff --git a/packages/core/core-flows/src/order/workflows/update-tax-lines.ts b/packages/core/core-flows/src/order/workflows/update-tax-lines.ts index e91ebb1ddee2f..90b57417bf9d5 100644 --- a/packages/core/core-flows/src/order/workflows/update-tax-lines.ts +++ b/packages/core/core-flows/src/order/workflows/update-tax-lines.ts @@ -119,18 +119,59 @@ const lineItemFields = [ "tax_lines.rate", "tax_lines.provider_id", ] +/** + * The data to update the order's tax lines. + */ export type UpdateOrderTaxLinesWorkflowInput = { + /** + * The ID of the order to update. + */ order_id: string + /** + * The IDs of the items to update the tax lines for. + */ item_ids?: string[] + /** + * The IDs of the shipping methods to update the tax lines for. + */ shipping_method_ids?: string[] + /** + * Whether to force the tax calculation. If enabled, the tax provider + * may send request to a third-party service to retrieve the calculated + * tax rates. This depends on the chosen tax provider in the order's tax region. + */ force_tax_calculation?: boolean + /** + * Whether to calculate the tax lines for a return. + */ is_return?: boolean + /** + * The shipping address to use for the tax calculation. + */ shipping_address?: OrderWorkflowDTO["shipping_address"] } export const updateOrderTaxLinesWorkflowId = "update-order-tax-lines" /** - * This workflow updates the tax lines of items and shipping methods in an order. + * This workflow updates the tax lines of items and shipping methods in an order. It's used by + * other order-related workflows, such as the {@link createOrderWorkflow} to set the order's + * tax lines. + * + * You can use this workflow within your customizations or your own custom workflows, allowing you to update an + * order's tax lines in your custom flows. + * + * @example + * const { result } = await updateOrderTaxLinesWorkflow(container) + * .run({ + * input: { + * order_id: "order_123", + * item_ids: ["orli_123", "orli_456"], + * } + * }) + * + * @summary + * + * Update the tax lines of items and shipping methods in an order. */ export const updateOrderTaxLinesWorkflow = createWorkflow( updateOrderTaxLinesWorkflowId, diff --git a/packages/core/core-flows/src/payment/workflows/process-payment.ts b/packages/core/core-flows/src/payment/workflows/process-payment.ts index c2af91e8c1ca5..63b1e903bf0f9 100644 --- a/packages/core/core-flows/src/payment/workflows/process-payment.ts +++ b/packages/core/core-flows/src/payment/workflows/process-payment.ts @@ -2,9 +2,9 @@ import { WebhookActionResult } from "@medusajs/types" import { PaymentActions } from "@medusajs/utils" import { createWorkflow, when } from "@medusajs/workflows-sdk" import { completeCartWorkflow } from "../../cart/workflows/complete-cart" +import { useQueryGraphStep } from "../../common" import { authorizePaymentSessionStep } from "../steps" import { capturePaymentWorkflow } from "./capture-payment" -import { useQueryGraphStep } from "../../common" interface ProcessPaymentWorkflowInput extends WebhookActionResult {} @@ -53,7 +53,7 @@ export const processPaymentWorkflow = createWorkflow( }) }) - when({ input }, ({ input }) => { + when({ input, paymentData }, ({ input, paymentData }) => { return ( input.action === PaymentActions.SUCCESSFUL && !!paymentData.data.length ) @@ -66,15 +66,18 @@ export const processPaymentWorkflow = createWorkflow( }) }) - when({ input }, ({ input }) => { - // Authorize payment session if no Cart is linked to the payment - // When associated with a Cart, the complete cart workflow will handle the authorization - return ( - !cartPaymentCollection.data.length && - input.action === PaymentActions.AUTHORIZED && - !!input.data?.session_id - ) - }).then(() => { + when( + { input, cartPaymentCollection }, + ({ input, cartPaymentCollection }) => { + // Authorize payment session if no Cart is linked to the payment + // When associated with a Cart, the complete cart workflow will handle the authorization + return ( + !cartPaymentCollection.data.length && + input.action === PaymentActions.AUTHORIZED && + !!input.data?.session_id + ) + } + ).then(() => { authorizePaymentSessionStep({ id: input.data!.session_id, context: {}, diff --git a/packages/core/core-flows/src/product/steps/batch-link-products-collection.ts b/packages/core/core-flows/src/product/steps/batch-link-products-collection.ts index 57246b305ecae..b524d6bcd3602 100644 --- a/packages/core/core-flows/src/product/steps/batch-link-products-collection.ts +++ b/packages/core/core-flows/src/product/steps/batch-link-products-collection.ts @@ -8,7 +8,14 @@ import { createStep, StepResponse } from "@medusajs/framework/workflows-sdk" export const batchLinkProductsToCollectionStepId = "batch-link-products-to-collection" /** - * This step creates links between product and collection records. + * This step manages the links between a collection and products. + * + * @example + * const data = batchLinkProductsToCollectionStep({ + * id: "collection_123", + * add: ["product_123"], + * remove: ["product_321"] + * }) */ export const batchLinkProductsToCollectionStep = createStep( batchLinkProductsToCollectionStepId, diff --git a/packages/core/core-flows/src/product/steps/batch-link-products-in-category.ts b/packages/core/core-flows/src/product/steps/batch-link-products-in-category.ts index 1c8e7057980f0..3a8f996d2dbe2 100644 --- a/packages/core/core-flows/src/product/steps/batch-link-products-in-category.ts +++ b/packages/core/core-flows/src/product/steps/batch-link-products-in-category.ts @@ -8,7 +8,14 @@ import { createStep, StepResponse } from "@medusajs/framework/workflows-sdk" export const batchLinkProductsToCategoryStepId = "batch-link-products-to-category" /** - * This step creates links between product and category records. + * This step manages the links between a category and products. + * + * @example + * const data = batchLinkProductsToCategoryStep({ + * id: "pcat_123", + * add: ["product_123"], + * remove: ["product_321"] + * }) */ export const batchLinkProductsToCategoryStep = createStep( batchLinkProductsToCategoryStepId, diff --git a/packages/core/core-flows/src/product/steps/create-product-options.ts b/packages/core/core-flows/src/product/steps/create-product-options.ts index ea8c9701fb410..9761786a76e76 100644 --- a/packages/core/core-flows/src/product/steps/create-product-options.ts +++ b/packages/core/core-flows/src/product/steps/create-product-options.ts @@ -5,6 +5,12 @@ import { StepResponse, createStep } from "@medusajs/framework/workflows-sdk" export const createProductOptionsStepId = "create-product-options" /** * This step creates one or more product options. + * + * @example + * const data = createProductOptionsStep([{ + * title: "Size", + * values: ["S", "M", "L"] + * }]) */ export const createProductOptionsStep = createStep( createProductOptionsStepId, diff --git a/packages/core/core-flows/src/product/steps/create-product-variants.ts b/packages/core/core-flows/src/product/steps/create-product-variants.ts index f88722b13c4f9..69b38bf7630f1 100644 --- a/packages/core/core-flows/src/product/steps/create-product-variants.ts +++ b/packages/core/core-flows/src/product/steps/create-product-variants.ts @@ -5,6 +5,15 @@ import { StepResponse, createStep } from "@medusajs/framework/workflows-sdk" export const createProductVariantsStepId = "create-product-variants" /** * This step creates one or more product variants. + * + * @example + * const data = createProductVariantsStep([{ + * title: "Small Shirt", + * options: { + * Size: "S", + * }, + * product_id: "prod_123", + * }]) */ export const createProductVariantsStep = createStep( createProductVariantsStepId, diff --git a/packages/core/core-flows/src/product/steps/create-products.ts b/packages/core/core-flows/src/product/steps/create-products.ts index 4a96df4bc8095..0f7615175b836 100644 --- a/packages/core/core-flows/src/product/steps/create-products.ts +++ b/packages/core/core-flows/src/product/steps/create-products.ts @@ -5,6 +5,25 @@ import { StepResponse, createStep } from "@medusajs/framework/workflows-sdk" export const createProductsStepId = "create-products" /** * This step creates one or more products. + * + * @example + * const data = createProductsStep([{ + * title: "Shirt", + * options: [ + * { + * title: "Size", + * values: ["S", "M", "L"] + * } + * ], + * variants: [ + * { + * title: "Small Shirt", + * options: { + * Size: "S" + * } + * } + * ] + * }]) */ export const createProductsStep = createStep( createProductsStepId, diff --git a/packages/core/core-flows/src/product/steps/create-variant-pricing-link.ts b/packages/core/core-flows/src/product/steps/create-variant-pricing-link.ts index 15d79700d02d8..980393cffe138 100644 --- a/packages/core/core-flows/src/product/steps/create-variant-pricing-link.ts +++ b/packages/core/core-flows/src/product/steps/create-variant-pricing-link.ts @@ -1,9 +1,21 @@ import { ContainerRegistrationKeys, Modules } from "@medusajs/framework/utils" import { createStep, StepResponse } from "@medusajs/framework/workflows-sdk" +/** + * The links to create between variant and price set records. + */ export type CreateVariantPricingLinkStepInput = { + /** + * The variant and price set record IDs to link. + */ links: { + /** + * The variant's ID. + */ variant_id: string + /** + * The price set's ID. + */ price_set_id: string }[] } @@ -11,6 +23,16 @@ export type CreateVariantPricingLinkStepInput = { export const createVariantPricingLinkStepId = "create-variant-pricing-link" /** * This step creates links between variant and price set records. + * + * @example + * const data = createVariantPricingLinkStep({ + * links: [ + * { + * variant_id: "variant_123", + * price_set_id: "pset_123" + * } + * ] + * }) */ export const createVariantPricingLinkStep = createStep( createVariantPricingLinkStepId, diff --git a/packages/core/core-flows/src/product/steps/delete-collections.ts b/packages/core/core-flows/src/product/steps/delete-collections.ts index 14f2b2ad9cad6..972dba99a26f6 100644 --- a/packages/core/core-flows/src/product/steps/delete-collections.ts +++ b/packages/core/core-flows/src/product/steps/delete-collections.ts @@ -2,13 +2,18 @@ import { IProductModuleService } from "@medusajs/framework/types" import { Modules } from "@medusajs/framework/utils" import { StepResponse, createStep } from "@medusajs/framework/workflows-sdk" +/** + * The IDs of the collections to delete. + */ +export type DeleteCollectionsStepInput = string[] + export const deleteCollectionsStepId = "delete-collections" /** * This step deletes one or more collections. */ export const deleteCollectionsStep = createStep( deleteCollectionsStepId, - async (ids: string[], { container }) => { + async (ids: DeleteCollectionsStepInput, { container }) => { const service = container.resolve(Modules.PRODUCT) await service.softDeleteProductCollections(ids) diff --git a/packages/core/core-flows/src/product/steps/delete-product-options.ts b/packages/core/core-flows/src/product/steps/delete-product-options.ts index ce3b04c5417f4..b106a4d0c2411 100644 --- a/packages/core/core-flows/src/product/steps/delete-product-options.ts +++ b/packages/core/core-flows/src/product/steps/delete-product-options.ts @@ -2,13 +2,18 @@ import { IProductModuleService } from "@medusajs/framework/types" import { Modules } from "@medusajs/framework/utils" import { StepResponse, createStep } from "@medusajs/framework/workflows-sdk" +/** + * The IDs of the product options to delete. + */ +export type DeleteProductOptionsStepInput = string[] + export const deleteProductOptionsStepId = "delete-product-options" /** * This step deletes one or more product options. */ export const deleteProductOptionsStep = createStep( deleteProductOptionsStepId, - async (ids: string[], { container }) => { + async (ids: DeleteProductOptionsStepInput, { container }) => { const service = container.resolve(Modules.PRODUCT) await service.softDeleteProductOptions(ids) diff --git a/packages/core/core-flows/src/product/steps/delete-product-tags.ts b/packages/core/core-flows/src/product/steps/delete-product-tags.ts index e962c8278bd3f..04ade4dd11055 100644 --- a/packages/core/core-flows/src/product/steps/delete-product-tags.ts +++ b/packages/core/core-flows/src/product/steps/delete-product-tags.ts @@ -2,13 +2,18 @@ import { IProductModuleService } from "@medusajs/framework/types" import { Modules } from "@medusajs/framework/utils" import { StepResponse, createStep } from "@medusajs/framework/workflows-sdk" +/** + * The IDs of the product tags to delete. + */ +export type DeleteProductTagsStepInput = string[] + export const deleteProductTagsStepId = "delete-product-tags" /** * This step deletes one or more product tags. */ export const deleteProductTagsStep = createStep( deleteProductTagsStepId, - async (ids: string[], { container }) => { + async (ids: DeleteProductTagsStepInput, { container }) => { const service = container.resolve(Modules.PRODUCT) await service.softDeleteProductTags(ids) diff --git a/packages/core/core-flows/src/product/steps/delete-product-types.ts b/packages/core/core-flows/src/product/steps/delete-product-types.ts index c464ba51a1592..32800a27d591e 100644 --- a/packages/core/core-flows/src/product/steps/delete-product-types.ts +++ b/packages/core/core-flows/src/product/steps/delete-product-types.ts @@ -2,13 +2,18 @@ import { IProductModuleService } from "@medusajs/framework/types" import { Modules } from "@medusajs/framework/utils" import { StepResponse, createStep } from "@medusajs/framework/workflows-sdk" +/** + * The IDs of the product types to delete. + */ +export type DeleteProductTypesStepInput = string[] + export const deleteProductTypesStepId = "delete-product-types" /** * This step deletes one or more product types. */ export const deleteProductTypesStep = createStep( deleteProductTypesStepId, - async (ids: string[], { container }) => { + async (ids: DeleteProductTypesStepInput, { container }) => { const service = container.resolve(Modules.PRODUCT) await service.softDeleteProductTypes(ids) diff --git a/packages/core/core-flows/src/product/steps/delete-product-variants.ts b/packages/core/core-flows/src/product/steps/delete-product-variants.ts index 94f09494434c4..3e42c06d80ef8 100644 --- a/packages/core/core-flows/src/product/steps/delete-product-variants.ts +++ b/packages/core/core-flows/src/product/steps/delete-product-variants.ts @@ -2,13 +2,18 @@ import { IProductModuleService } from "@medusajs/framework/types" import { Modules } from "@medusajs/framework/utils" import { StepResponse, createStep } from "@medusajs/framework/workflows-sdk" +/** + * The IDs of the product variants to delete. + */ +export type DeleteProductVariantsStepInput = string[] + export const deleteProductVariantsStepId = "delete-product-variants" /** * This step deletes one or more product variants. */ export const deleteProductVariantsStep = createStep( deleteProductVariantsStepId, - async (ids: string[], { container }) => { + async (ids: DeleteProductVariantsStepInput, { container }) => { const service = container.resolve(Modules.PRODUCT) await service.softDeleteProductVariants(ids) diff --git a/packages/core/core-flows/src/product/steps/delete-products.ts b/packages/core/core-flows/src/product/steps/delete-products.ts index 4080acbb67c3a..6f649778df572 100644 --- a/packages/core/core-flows/src/product/steps/delete-products.ts +++ b/packages/core/core-flows/src/product/steps/delete-products.ts @@ -2,13 +2,18 @@ import { IProductModuleService } from "@medusajs/framework/types" import { Modules } from "@medusajs/framework/utils" import { StepResponse, createStep } from "@medusajs/framework/workflows-sdk" +/** + * The IDs of the products to delete. + */ +export type DeleteProductsStepInput = string[] + export const deleteProductsStepId = "delete-products" /** * This step deletes one or more products. */ export const deleteProductsStep = createStep( deleteProductsStepId, - async (ids: string[], { container }) => { + async (ids: DeleteProductsStepInput, { container }) => { const service = container.resolve(Modules.PRODUCT) await service.softDeleteProducts(ids) diff --git a/packages/core/core-flows/src/product/steps/generate-product-csv.ts b/packages/core/core-flows/src/product/steps/generate-product-csv.ts index a095bc400ddd9..148f83089b4a7 100644 --- a/packages/core/core-flows/src/product/steps/generate-product-csv.ts +++ b/packages/core/core-flows/src/product/steps/generate-product-csv.ts @@ -58,13 +58,42 @@ const csvSortFunction = (a: string, b: string) => { return a.localeCompare(b) } +/** + * The products to export. + */ +export type GenerateProductCsvStepInput = HttpTypes.AdminProduct[] + +/** + * The export's details. + */ +export type GenerateProductCsvStepOutput = { + /** + * The ID of the generated file as returned by the [File Module Provider](https://docs.medusajs.com/resources/architectural-modules/file). + */ + id: string + /** + * The name of the generated file as returned by the [File Module Provider](https://docs.medusajs.com/resources/architectural-modules/file). + */ + filename: string +} + export const generateProductCsvStepId = "generate-product-csv" /** - * This step generates a CSV file to be exported. + * This step generates a CSV file that exports products. The CSV + * file is created and stored using the registered [File Module Provider](https://docs.medusajs.com/resources/architectural-modules/file). + * + * @example + * const { data: products } = useQueryGraphStep({ + * entity: "product", + * fields: ["*", "variants.*", "collection.*", "categories.*"] + * }) + * + * // @ts-ignore + * const data = generateProductCsvStep(products) */ export const generateProductCsvStep = createStep( generateProductCsvStepId, - async (products: HttpTypes.AdminProduct[], { container }) => { + async (products: GenerateProductCsvStepInput, { container }) => { const regionService = container.resolve( Modules.REGION ) @@ -88,7 +117,10 @@ export const generateProductCsvStep = createStep( content: csvContent, }) - return new StepResponse({ id: file.id, filename }, file.id) + return new StepResponse( + { id: file.id, filename } as GenerateProductCsvStepOutput, + file.id + ) }, async (fileId, { container }) => { if (!fileId) { diff --git a/packages/core/core-flows/src/product/steps/get-all-products.ts b/packages/core/core-flows/src/product/steps/get-all-products.ts index 855150d6a7ddf..775e34a48e90c 100644 --- a/packages/core/core-flows/src/product/steps/get-all-products.ts +++ b/packages/core/core-flows/src/product/steps/get-all-products.ts @@ -5,14 +5,44 @@ import { import { ContainerRegistrationKeys } from "@medusajs/framework/utils" import { createStep, StepResponse } from "@medusajs/framework/workflows-sdk" +/** + * The configuration to retrieve the products. + */ export type GetAllProductsStepInput = { + /** + * The fields to select. These fields will be passed to + * [Query](https://docs.medusajs.com/learn/fundamentals/module-links/query), so you can + * pass product properties or any relation names, including custom links. + */ select: string[] + /** + * The filters to select which products to retrieve. + */ filter?: FilterableProductProps } export const getAllProductsStepId = "get-all-products" /** - * This step retrieves all products. + * This step retrieves all products matching a set of filters. + * + * @example + * To retrieve all products: + * + * ```ts + * const data = getAllProductsStep({ + * select: ["*"], + * }) + * ``` + * + * To retrieve all products matching a filter: + * + * ```ts + * const data = getAllProductsStep({ + * select: ["*"], + * filter: { + * collection_id: "collection_123" + * } + * }) */ export const getAllProductsStep = createStep( getAllProductsStepId, diff --git a/packages/core/core-flows/src/product/steps/get-products.ts b/packages/core/core-flows/src/product/steps/get-products.ts index f554570235d71..ab85b415d3279 100644 --- a/packages/core/core-flows/src/product/steps/get-products.ts +++ b/packages/core/core-flows/src/product/steps/get-products.ts @@ -2,13 +2,19 @@ import { IProductModuleService } from "@medusajs/framework/types" import { Modules } from "@medusajs/framework/utils" import { createStep, StepResponse } from "@medusajs/framework/workflows-sdk" +/** + * Configurations to retrieve products. + */ export type GetProductsStepInput = { + /** + * The IDs of the products to retrieve. + */ ids?: string[] } export const getProductsStepId = "get-products" /** - * This step retrieves products. + * This step retrieves products, with ability to filter by product IDs. */ export const getProductsStep = createStep( getProductsStepId, diff --git a/packages/core/core-flows/src/product/steps/get-variant-availability.ts b/packages/core/core-flows/src/product/steps/get-variant-availability.ts index c7bcb47942707..075febd2e3011 100644 --- a/packages/core/core-flows/src/product/steps/get-variant-availability.ts +++ b/packages/core/core-flows/src/product/steps/get-variant-availability.ts @@ -4,14 +4,29 @@ import { getVariantAvailability, } from "@medusajs/framework/utils" +/** + * The details required to compute the inventory availability for a list of variants in a given sales channel. + */ export type GetVariantAvailabilityStepInput = { + /** + * The IDs of the variants to retrieve their availability. + */ variant_ids: string[] + /** + * The ID of the sales channel to retrieve the variant availability in. + */ sales_channel_id: string } export const getVariantAvailabilityId = "get-variant-availability" /** - * Computes the varaint availability for a list of variants in a given sales channel + * This step computes the inventory availability for a list of variants in a given sales channel. + * + * @example + * const data = getVariantAvailabilityStep({ + * variant_ids: ["variant_123"], + * sales_channel_id: "sc_123" + * }) */ export const getVariantAvailabilityStep = createStep( getVariantAvailabilityId, diff --git a/packages/core/core-flows/src/product/steps/get-variant-pricing-link.ts b/packages/core/core-flows/src/product/steps/get-variant-pricing-link.ts index 42923590a455e..3be377df1a4a0 100644 --- a/packages/core/core-flows/src/product/steps/get-variant-pricing-link.ts +++ b/packages/core/core-flows/src/product/steps/get-variant-pricing-link.ts @@ -6,7 +6,13 @@ import { } from "@medusajs/framework/utils" import { createStep, StepResponse } from "@medusajs/framework/workflows-sdk" +/** + * The configurations to retrieve pricing links for product variants. + */ export type GetVariantPricingLinkStepInput = { + /** + * The IDs of the product variants to retrieve pricing links for. + */ ids: string[] } diff --git a/packages/core/core-flows/src/product/steps/group-products-for-batch.ts b/packages/core/core-flows/src/product/steps/group-products-for-batch.ts index b3b381f426300..f62c4e0ef04a4 100644 --- a/packages/core/core-flows/src/product/steps/group-products-for-batch.ts +++ b/packages/core/core-flows/src/product/steps/group-products-for-batch.ts @@ -2,14 +2,72 @@ import { HttpTypes, IProductModuleService } from "@medusajs/framework/types" import { Modules } from "@medusajs/framework/utils" import { StepResponse, createStep } from "@medusajs/framework/workflows-sdk" +/** + * The products to group. + */ +export type GroupProductsForBatchStepInput = (HttpTypes.AdminCreateProduct & { + /** + * The ID of the product to update. + */ + id?: string +})[] + +export type GroupProductsForBatchStepOutput = { + /** + * The products to create. + */ + create: HttpTypes.AdminCreateProduct[] + /** + * The products to update. + */ + update: (HttpTypes.AdminUpdateProduct & { id: string })[] +} + export const groupProductsForBatchStepId = "group-products-for-batch" /** - * This step groups products to be created and updated. + * This step groups products to be created or updated. + * + * @example + * const data = groupProductsForBatchStep([ + * { + * id: "prod_123", + * title: "Shirt", + * options: [ + * { + * title: "Size", + * values: ["S", "M", "L"] + * } + * ] + * }, + * { + * title: "Pants", + * options: [ + * { + * title: "Color", + * values: ["Red", "Blue"] + * } + * ], + * variants: [ + * { + * title: "Red Pants", + * options: { + * Color: "Red" + * }, + * prices: [ + * { + * amount: 10, + * currency_code: "usd" + * } + * ] + * } + * ] + * } + * ]) */ export const groupProductsForBatchStep = createStep( groupProductsForBatchStepId, async ( - data: (HttpTypes.AdminCreateProduct & { id?: string })[], + data: GroupProductsForBatchStepInput, { container } ) => { const service = container.resolve(Modules.PRODUCT) @@ -52,6 +110,8 @@ export const groupProductsForBatchStep = createStep( { toUpdate: [], toCreate: [] } ) - return new StepResponse({ create: toCreate, update: toUpdate }) + return new StepResponse( + { create: toCreate, update: toUpdate } as GroupProductsForBatchStepOutput, + ) } ) diff --git a/packages/core/core-flows/src/product/steps/index.ts b/packages/core/core-flows/src/product/steps/index.ts index 37e7f0ec674a6..79e3db53fa2b4 100644 --- a/packages/core/core-flows/src/product/steps/index.ts +++ b/packages/core/core-flows/src/product/steps/index.ts @@ -14,6 +14,7 @@ export * from "./create-collections" export * from "./update-collections" export * from "./delete-collections" export * from "./batch-link-products-collection" +export * from "./batch-link-products-in-category" export * from "./create-product-types" export * from "./update-product-types" export * from "./delete-product-types" @@ -24,3 +25,4 @@ export * from "./generate-product-csv" export * from "./parse-product-csv" export * from "./group-products-for-batch" export * from "./wait-confirmation-product-import" +export * from "./get-variant-availability" \ No newline at end of file diff --git a/packages/core/core-flows/src/product/steps/parse-product-csv.ts b/packages/core/core-flows/src/product/steps/parse-product-csv.ts index 5bacf3c966fd5..933de4ba1e85c 100644 --- a/packages/core/core-flows/src/product/steps/parse-product-csv.ts +++ b/packages/core/core-flows/src/product/steps/parse-product-csv.ts @@ -9,13 +9,22 @@ import { normalizeForImport } from "../helpers/normalize-for-import" import { normalizeV1Products } from "../helpers/normalize-v1-import" import { convertCsvToJson } from "../utlils" +/** + * The CSV file content to parse. + */ +export type ParseProductCsvStepInput = string + export const parseProductCsvStepId = "parse-product-csv" /** - * This step parses a CSV file holding products to import. + * This step parses a CSV file holding products to import, returning the products as + * objects that can be imported. + * + * @example + * const data = parseProductCsvStep("products.csv") */ export const parseProductCsvStep = createStep( parseProductCsvStepId, - async (fileContent: string, { container }) => { + async (fileContent: ParseProductCsvStepInput, { container }) => { const regionService = container.resolve( Modules.REGION ) diff --git a/packages/core/core-flows/src/product/steps/update-collections.ts b/packages/core/core-flows/src/product/steps/update-collections.ts index 4745509c14b2c..7a31260f2f0d6 100644 --- a/packages/core/core-flows/src/product/steps/update-collections.ts +++ b/packages/core/core-flows/src/product/steps/update-collections.ts @@ -5,14 +5,33 @@ import { } from "@medusajs/framework/utils" import { StepResponse, createStep } from "@medusajs/framework/workflows-sdk" +/** + * The data to identify and update the product collections. + */ export type UpdateCollectionsStepInput = { + /** + * The filters to select the collections to update. + */ selector: ProductTypes.FilterableProductCollectionProps + /** + * The data to update the collections with. + */ update: ProductTypes.UpdateProductCollectionDTO } export const updateCollectionsStepId = "update-collections" /** * This step updates collections matching the specified filters. + * + * @example + * const data = updateCollectionsStep({ + * selector: { + * id: "collection_123" + * }, + * update: { + * title: "Summer Collection" + * } + * }) */ export const updateCollectionsStep = createStep( updateCollectionsStepId, diff --git a/packages/core/core-flows/src/product/steps/update-product-options.ts b/packages/core/core-flows/src/product/steps/update-product-options.ts index f29c96971bf62..121c5c6ff2e43 100644 --- a/packages/core/core-flows/src/product/steps/update-product-options.ts +++ b/packages/core/core-flows/src/product/steps/update-product-options.ts @@ -5,14 +5,33 @@ import { } from "@medusajs/framework/utils" import { StepResponse, createStep } from "@medusajs/framework/workflows-sdk" +/** + * The data to identify and update the product options. + */ export type UpdateProductOptionsStepInput = { + /** + * The filters to select the product options to update. + */ selector: ProductTypes.FilterableProductOptionProps + /** + * The data to update the product options with. + */ update: ProductTypes.UpdateProductOptionDTO } export const updateProductOptionsStepId = "update-product-options" /** * This step updates product options matching the specified filters. + * + * @example + * const data = updateProductOptionsStep({ + * selector: { + * id: "popt_123" + * }, + * update: { + * title: "Size" + * } + * }) */ export const updateProductOptionsStep = createStep( updateProductOptionsStepId, diff --git a/packages/core/core-flows/src/product/steps/update-product-tags.ts b/packages/core/core-flows/src/product/steps/update-product-tags.ts index 0965693e614d7..b78b48b3e033b 100644 --- a/packages/core/core-flows/src/product/steps/update-product-tags.ts +++ b/packages/core/core-flows/src/product/steps/update-product-tags.ts @@ -5,14 +5,33 @@ import { } from "@medusajs/framework/utils" import { StepResponse, createStep } from "@medusajs/framework/workflows-sdk" +/** + * The data to identify and update the product tags. + */ export type UpdateProductTagsStepInput = { + /** + * The filters to select the product tags to update. + */ selector: ProductTypes.FilterableProductTagProps + /** + * The data to update the product tags with. + */ update: ProductTypes.UpdateProductTagDTO } export const updateProductTagsStepId = "update-product-tags" /** * This step updates product tags matching the specified filters. + * + * @example + * const data = updateProductTagsStep({ + * selector: { + * id: "popt_123" + * }, + * update: { + * value: "clothing" + * } + * }) */ export const updateProductTagsStep = createStep( updateProductTagsStepId, diff --git a/packages/core/core-flows/src/product/steps/update-product-types.ts b/packages/core/core-flows/src/product/steps/update-product-types.ts index 6d2415e474c7c..e81b9c4ebb32c 100644 --- a/packages/core/core-flows/src/product/steps/update-product-types.ts +++ b/packages/core/core-flows/src/product/steps/update-product-types.ts @@ -5,14 +5,33 @@ import { } from "@medusajs/framework/utils" import { StepResponse, createStep } from "@medusajs/framework/workflows-sdk" +/** + * The data to identify and update the product tags. + */ export type UpdateProductTypesStepInput = { + /** + * The filters to select the product types to update. + */ selector: ProductTypes.FilterableProductTypeProps + /** + * The data to update the product types with. + */ update: ProductTypes.UpdateProductTypeDTO } export const updateProductTypesStepId = "update-product-types" /** * This step updates product types matching the specified filters. + * + * @example + * const data = updateProductTypesStep({ + * selector: { + * id: "popt_123" + * }, + * update: { + * value: "clothing" + * } + * }) */ export const updateProductTypesStep = createStep( updateProductTypesStepId, diff --git a/packages/core/core-flows/src/product/steps/update-product-variants.ts b/packages/core/core-flows/src/product/steps/update-product-variants.ts index db9403dfc9edc..7556d4d358bcd 100644 --- a/packages/core/core-flows/src/product/steps/update-product-variants.ts +++ b/packages/core/core-flows/src/product/steps/update-product-variants.ts @@ -6,18 +6,57 @@ import { } from "@medusajs/framework/utils" import { StepResponse, createStep } from "@medusajs/framework/workflows-sdk" +/** + * The details of the product variants update. + */ export type UpdateProductVariantsStepInput = | { + /** + * The filters to select the product variants to update. + */ selector: ProductTypes.FilterableProductVariantProps + /** + * The data to update the product variants with. + */ update: ProductTypes.UpdateProductVariantDTO } | { + /** + * The data to create or update product variants. + */ product_variants: ProductTypes.UpsertProductVariantDTO[] } export const updateProductVariantsStepId = "update-product-variants" /** * This step updates one or more product variants. + * + * @example + * To update product variants by their ID: + * + * ```ts + * const data = updateProductVariantsStep({ + * product_variants: [ + * { + * id: "variant_123", + * title: "Small Shirt" + * } + * ] + * }) + * ``` + * + * To update product variants matching a filter: + * + * ```ts + * const data = updateProductVariantsStep({ + * selector: { + * product_id: "prod_123", + * }, + * update: { + * material: "cotton", + * } + * }) + * ``` */ export const updateProductVariantsStep = createStep( updateProductVariantsStepId, diff --git a/packages/core/core-flows/src/product/steps/update-products.ts b/packages/core/core-flows/src/product/steps/update-products.ts index acf86bcb13fad..599625185f3ca 100644 --- a/packages/core/core-flows/src/product/steps/update-products.ts +++ b/packages/core/core-flows/src/product/steps/update-products.ts @@ -6,18 +6,57 @@ import { } from "@medusajs/framework/utils" import { StepResponse, createStep } from "@medusajs/framework/workflows-sdk" +/** + * The details of the products update. + */ export type UpdateProductsStepInput = | { + /** + * The filters to select the products to update. + */ selector: ProductTypes.FilterableProductProps + /** + * The data to update the products with. + */ update: ProductTypes.UpdateProductDTO } | { + /** + * The data to create or update products. + */ products: ProductTypes.UpsertProductDTO[] } export const updateProductsStepId = "update-products" /** * This step updates one or more products. + * + * @example + * To update products by their ID: + * + * ```ts + * const data = updateProductsStep({ + * products: [ + * { + * id: "prod_123", + * title: "Shirt" + * } + * ] + * }) + * ``` + * + * To update products matching a filter: + * + * ```ts + * const data = updateProductsStep({ + * selector: { + * collection_id: "collection_123", + * }, + * update: { + * material: "cotton", + * } + * }) + * ``` */ export const updateProductsStep = createStep( updateProductsStepId, diff --git a/packages/core/core-flows/src/product/steps/wait-confirmation-product-import.ts b/packages/core/core-flows/src/product/steps/wait-confirmation-product-import.ts index 231ae19b41355..1dd894acca6b5 100644 --- a/packages/core/core-flows/src/product/steps/wait-confirmation-product-import.ts +++ b/packages/core/core-flows/src/product/steps/wait-confirmation-product-import.ts @@ -3,7 +3,10 @@ import { createStep } from "@medusajs/framework/workflows-sdk" export const waitConfirmationProductImportStepId = "wait-confirmation-product-import" /** - * This step waits until a product import is confirmed. + * This step waits until a product import is confirmed. It's useful before executing the + * {@link batchProductsWorkflow}. + * + * This step is asynchronous and will make the workflow using it a [Long-Running Workflow](https://docs.medusajs.com/learn/fundamentals/workflows/long-running-workflow). */ export const waitConfirmationProductImportStep = createStep( { diff --git a/packages/core/core-flows/src/product/workflows/batch-link-products-collection.ts b/packages/core/core-flows/src/product/workflows/batch-link-products-collection.ts index 1e4352347ca83..e90ac1c909bfb 100644 --- a/packages/core/core-flows/src/product/workflows/batch-link-products-collection.ts +++ b/packages/core/core-flows/src/product/workflows/batch-link-products-collection.ts @@ -6,7 +6,24 @@ export const batchLinkProductsToCollectionWorkflowId = "batch-link-products-to-collection" /** - * This workflow creates links between product and collection records. + * This workflow manages the links between a collection and products. It's used by the + * [Manage Products of Collection Admin API Route](https://docs.medusajs.com/api/admin#collections_postcollectionsidproducts). + * + * You can use this workflow within your own custom workflows to manage the products in a collection. + * + * @example + * const { result } = await batchLinkProductsToCollectionWorkflow(container) + * .run({ + * input: { + * id: "pcol_123", + * add: ["prod_123"], + * remove: ["prod_456"], + * } + * }) + * + * @summary + * + * Manage the links between a collection and products. */ export const batchLinkProductsToCollectionWorkflow = createWorkflow( batchLinkProductsToCollectionWorkflowId, diff --git a/packages/core/core-flows/src/product/workflows/batch-product-variants.ts b/packages/core/core-flows/src/product/workflows/batch-product-variants.ts index 84194a6a604f0..cb823470e25bf 100644 --- a/packages/core/core-flows/src/product/workflows/batch-product-variants.ts +++ b/packages/core/core-flows/src/product/workflows/batch-product-variants.ts @@ -16,20 +16,61 @@ import { createProductVariantsWorkflow } from "./create-product-variants" import { updateProductVariantsWorkflow } from "./update-product-variants" import { deleteProductVariantsWorkflow } from "./delete-product-variants" +/** + * The product variants to manage. + */ +export type BatchProductVariantsWorkflowInput = BatchWorkflowInput< + CreateProductVariantWorkflowInputDTO, + UpdateProductVariantWorkflowInputDTO +> + +/** + * The result of managing the product variants. + */ +export type BatchProductVariantsWorkflowOutput = BatchWorkflowOutput + export const batchProductVariantsWorkflowId = "batch-product-variants" /** - * This workflow creates, updates, and deletes product variants. + * This workflow creates, updates, and deletes product variants. It's used by the + * [Manage Variants in a Product Admin API Route](https://docs.medusajs.com/api/admin#products_postproductsidvariantsbatch). + * + * You can use this workflow within your own custom workflows to manage the variants of a product. You can also + * use this within a [seed script](https://docs.medusajs.com/learn/fundamentals/custom-cli-scripts/seed-data) or in a custom import script. + * + * @example + * const { result } = await batchProductVariantsWorkflow(container) + * .run({ + * input: { + * create: [ + * { + * title: "Small Shirt", + * product_id: "prod_123", + * options: { + * Size: "S" + * }, + * prices: [ + * { + * amount: 10, + * currency_code: "usd" + * } + * ] + * } + * ], + * update: [ + * { + * id: "variant_123", + * title: "Red Pants" + * } + * ], + * delete: ["variant_321"] + * } + * }) */ export const batchProductVariantsWorkflow = createWorkflow( batchProductVariantsWorkflowId, ( - input: WorkflowData< - BatchWorkflowInput< - CreateProductVariantWorkflowInputDTO, - UpdateProductVariantWorkflowInputDTO - > - > - ): WorkflowResponse> => { + input: WorkflowData + ): WorkflowResponse => { const normalizedInput = transform({ input }, (data) => { return { create: data.input.create ?? [], diff --git a/packages/core/core-flows/src/product/workflows/batch-products-in-category.ts b/packages/core/core-flows/src/product/workflows/batch-products-in-category.ts index 677dc5452e227..bf5f95afe6444 100644 --- a/packages/core/core-flows/src/product/workflows/batch-products-in-category.ts +++ b/packages/core/core-flows/src/product/workflows/batch-products-in-category.ts @@ -5,7 +5,24 @@ import { batchLinkProductsToCategoryStep } from "../steps/batch-link-products-in export const batchLinkProductsToCategoryWorkflowId = "batch-link-products-to-category" /** - * This workflow creates links between product and category records. + * This workflow manages the links between a category and products. It's used by the + * [Manage Products of Category Admin API Route](https://docs.medusajs.com/api/admin#product-categories_postproductcategoriesidproducts). + * + * You can use this workflow within your own custom workflows to manage the products in a category. + * + * @example + * const { result } = await batchLinkProductsToCategoryWorkflow(container) + * .run({ + * input: { + * id: "pcat_123", + * add: ["prod_123"], + * remove: ["prod_321"] + * } + * }) + * + * @summary + * + * Manage the links between a collection and products. */ export const batchLinkProductsToCategoryWorkflow = createWorkflow( batchLinkProductsToCategoryWorkflowId, diff --git a/packages/core/core-flows/src/product/workflows/batch-products.ts b/packages/core/core-flows/src/product/workflows/batch-products.ts index 76e1af13d830a..915f1bac75725 100644 --- a/packages/core/core-flows/src/product/workflows/batch-products.ts +++ b/packages/core/core-flows/src/product/workflows/batch-products.ts @@ -16,19 +16,69 @@ import { createProductsWorkflow } from "./create-products" import { deleteProductsWorkflow } from "./delete-products" import { updateProductsWorkflow } from "./update-products" +/** + * The products to manage. + */ +export type BatchProductWorkflowInput = BatchWorkflowInput< + CreateProductWorkflowInputDTO, + UpdateProductWorkflowInputDTO +> + export const batchProductsWorkflowId = "batch-products" /** - * This workflow creates, updates, or deletes products. + * This workflow creates, updates, or deletes products. It's used by the + * [Manage Products Admin API Route](https://docs.medusajs.com/api/admin#products_postproductsbatch). + * + * You can use this workflow within your own custom workflows to manage products in bulk. This is + * also useful when writing a [seed script](https://docs.medusajs.com/learn/fundamentals/custom-cli-scripts/seed-data) or a custom import script. + * + * @example + * const { result } = await batchProductsWorkflow(container) + * .run({ + * input: { + * create: [ + * { + * title: "Shirt", + * options: [ + * { + * title: "Color", + * values: ["Red", "Brown"] + * } + * ], + * variants: [ + * { + * title: "Red Shirt", + * options: { + * "Color": "Red" + * }, + * prices: [ + * { + * amount: 10, + * currency_code: "usd" + * } + * ] + * } + * ] + * } + * ], + * update: [ + * { + * id: "prod_123", + * title: "Pants" + * } + * ], + * delete: ["prod_321"] + * } + * }) + * + * @summary + * + * Manage products in bulk. */ export const batchProductsWorkflow = createWorkflow( batchProductsWorkflowId, ( - input: WorkflowData< - BatchWorkflowInput< - CreateProductWorkflowInputDTO, - UpdateProductWorkflowInputDTO - > - > + input: WorkflowData ): WorkflowResponse> => { const res = parallelize( createProductsWorkflow.runAsStep({ diff --git a/packages/core/core-flows/src/product/workflows/create-collections.ts b/packages/core/core-flows/src/product/workflows/create-collections.ts index dd9621119ecf9..9adafba77fb42 100644 --- a/packages/core/core-flows/src/product/workflows/create-collections.ts +++ b/packages/core/core-flows/src/product/workflows/create-collections.ts @@ -10,13 +10,46 @@ import { import { emitEventStep } from "../../common" import { createCollectionsStep } from "../steps" +/** + * The details of the collection to create, along with custom data that's passed to the workflow's hooks. + */ export type CreateCollectionsWorkflowInput = { + /** + * The collections to create. + */ collections: ProductTypes.CreateProductCollectionDTO[] } & AdditionalData export const createCollectionsWorkflowId = "create-collections" /** - * This workflow creates one or more collections. + * This workflow creates one or more collections. It's used by the + * [Create Collection Admin API Route](https://docs.medusajs.com/api/admin#collections_postcollections). + * + * This workflow has a hook that allows you to perform custom actions on the created collections. For example, you can pass under `additional_data` custom data that + * allows you to create custom data models linked to the product collections. + * + * You can also use this workflow within your own custom workflows, allowing you to wrap custom logic around product-collection creation. + * + * @example + * const { result } = await createCollectionsWorkflow(container) + * .run({ + * input: { + * collections: [ + * { + * title: "Summer Clothing" + * } + * ], + * additional_data: { + * erp_id: "123" + * } + * } + * }) + * + * @summary + * + * Create one or more product collections. + * + * @property hooks.collectionsCreated - This hook is executed after the collections are created. You can consume this hook to perform custom actions on the created collections. */ export const createCollectionsWorkflow = createWorkflow( createCollectionsWorkflowId, diff --git a/packages/core/core-flows/src/product/workflows/create-product-options.ts b/packages/core/core-flows/src/product/workflows/create-product-options.ts index 7807eea1b975c..070d1e2acf457 100644 --- a/packages/core/core-flows/src/product/workflows/create-product-options.ts +++ b/packages/core/core-flows/src/product/workflows/create-product-options.ts @@ -27,7 +27,7 @@ export const createProductOptionsWorkflowId = "create-product-options" * This workflow has a hook that allows you to perform custom actions on the created product options. For example, you can pass under `additional_data` custom data that * allows you to create custom data models linked to the product options. * - * You can also use this workflow within your own custom workflows, allowing you to wrap custom logic around product-option creation. + * You can also use this workflow within your customizations or your own custom workflows, allowing you to wrap custom logic around product-option creation. * * @example * const { result } = await createProductOptionsWorkflow(container) diff --git a/packages/core/core-flows/src/product/workflows/create-product-tags.ts b/packages/core/core-flows/src/product/workflows/create-product-tags.ts index 5486d8cff9fd4..970246087fde2 100644 --- a/packages/core/core-flows/src/product/workflows/create-product-tags.ts +++ b/packages/core/core-flows/src/product/workflows/create-product-tags.ts @@ -10,13 +10,46 @@ import { import { emitEventStep } from "../../common/steps/emit-event" import { createProductTagsStep } from "../steps" +/** + * The data to create one or more product tags, along with custom data that's passed to the workflow's hooks. + */ export type CreateProductTagsWorkflowInput = { + /** + * The product tags to create. + */ product_tags: ProductTypes.CreateProductTagDTO[] } & AdditionalData export const createProductTagsWorkflowId = "create-product-tags" /** - * This workflow creates one or more product tags. + * This workflow creates one or more product tags. It's used by the + * [Create Product Tag Admin API Route](https://docs.medusajs.com/api/admin#product-tags_postproducttags). + * + * This workflow has a hook that allows you to perform custom actions on the created product tags. For example, you can pass under `additional_data` custom data that + * allows you to create custom data models linked to the product tags. + * + * You can also use this workflow within your own custom workflows, allowing you to wrap custom logic around product-tag creation. + * + * @example + * const { result } = await createProductTagsWorkflow(container) + * .run({ + * input: { + * product_tags: [ + * { + * value: "clothing" + * } + * ], + * additional_data: { + * erp_id: "123" + * } + * } + * }) + * + * @summary + * + * Create one or more product tags. + * + * @property hooks.productTagsCreated - This hook is executed after the product tags are created. You can consume this hook to perform custom actions on the created product tags. */ export const createProductTagsWorkflow = createWorkflow( createProductTagsWorkflowId, diff --git a/packages/core/core-flows/src/product/workflows/create-product-types.ts b/packages/core/core-flows/src/product/workflows/create-product-types.ts index e9c81b35df39b..66dc5bc36e024 100644 --- a/packages/core/core-flows/src/product/workflows/create-product-types.ts +++ b/packages/core/core-flows/src/product/workflows/create-product-types.ts @@ -10,13 +10,46 @@ import { import { emitEventStep } from "../../common/steps/emit-event" import { createProductTypesStep } from "../steps" +/** + * The data to create one or more product types, along with custom data that's passed to the workflow's hooks. + */ export type CreateProductTypesWorkflowInput = { + /** + * The product types to create. + */ product_types: ProductTypes.CreateProductTypeDTO[] } & AdditionalData export const createProductTypesWorkflowId = "create-product-types" /** - * This workflow creates one or more product types. + * This workflow creates one or more product types. It's used by the + * [Create Product Type Admin API Route](https://docs.medusajs.com/api/admin#product-types_postproducttypes). + * + * This workflow has a hook that allows you to perform custom actions on the created product types. For example, you can pass under `additional_data` custom data that + * allows you to create custom data models linked to the product types. + * + * You can also use this workflow within your own custom workflows, allowing you to wrap custom logic around product-type creation. + * + * @example + * const { result } = await createProductTypesWorkflow(container) + * .run({ + * input: { + * product_types: [ + * { + * value: "clothing" + * } + * ], + * additional_data: { + * erp_id: "123" + * } + * } + * }) + * + * @summary + * + * Create one or more product types. + * + * @property hooks.productTypesCreated - This hook is executed after the product types are created. You can consume this hook to perform custom actions on the created product types. */ export const createProductTypesWorkflow = createWorkflow( createProductTypesWorkflowId, diff --git a/packages/core/core-flows/src/product/workflows/create-product-variants.ts b/packages/core/core-flows/src/product/workflows/create-product-variants.ts index 1bd16ccf2db73..123464fad73c6 100644 --- a/packages/core/core-flows/src/product/workflows/create-product-variants.ts +++ b/packages/core/core-flows/src/product/workflows/create-product-variants.ts @@ -205,7 +205,7 @@ export const createProductVariantsWorkflowId = "create-product-variants" * This workflow has a hook that allows you to perform custom actions on the created product variants. For example, you can pass under `additional_data` custom data that * allows you to create custom data models linked to the product variants. * - * You can also use this workflow within your own custom workflows, allowing you to wrap custom logic around product-variant creation. + * You can also use this workflow within your customizations or your own custom workflows, allowing you to wrap custom logic around product-variant creation. * * @example * const { result } = await createProductVariantsWorkflow(container) diff --git a/packages/core/core-flows/src/product/workflows/create-products.ts b/packages/core/core-flows/src/product/workflows/create-products.ts index 9cecee9ebc3ca..e475810d82cb6 100644 --- a/packages/core/core-flows/src/product/workflows/create-products.ts +++ b/packages/core/core-flows/src/product/workflows/create-products.ts @@ -22,13 +22,51 @@ import { associateProductsWithSalesChannelsStep } from "../../sales-channel" import { createProductsStep } from "../steps/create-products" import { createProductVariantsWorkflow } from "./create-product-variants" -interface ValidateProductInputStepInput { +/** + * The product's data to validate. + */ +export interface ValidateProductInputStepInput { + /** + * The products to validate. + */ products: CreateProductWorkflowInputDTO[] } const validateProductInputStepId = "validate-product-input" /** - * This step validates a product data before creation. + * This step validates that all provided products have options. + * If a product is missing options, an error is thrown. + * + * @example + * const data = validateProductInputStep({ + * products: [ + * { + * title: "Shirt", + * options: [ + * { + * title: "Size", + * values: ["S", "M", "L"] + * } + * ], + * variants: [ + * { + * title: "Small Shirt", + * sku: "SMALLSHIRT", + * options: { + * Size: "S" + * }, + * prices: [ + * { + * amount: 10, + * currency_code: "usd" + * } + * ], + * manage_inventory: true, + * }, + * ] + * } + * ] + * }) */ export const validateProductInputStep = createStep( validateProductInputStepId, @@ -67,7 +105,7 @@ export const createProductsWorkflowId = "create-products" * * This workflow has a hook that allows you to perform custom actions on the created products. You can see an example in [this guide](https://docs.medusajs.com/resources/commerce-modules/product/extend). * - * You can also use this workflow within your own custom workflows, allowing you to wrap custom logic around product creation. + * You can also use this workflow within your customizations or your own custom workflows, allowing you to wrap custom logic around product creation. * * @example * const { result } = await createProductsWorkflow(container) diff --git a/packages/core/core-flows/src/product/workflows/delete-collections.ts b/packages/core/core-flows/src/product/workflows/delete-collections.ts index dae977fceb547..68464b57e3185 100644 --- a/packages/core/core-flows/src/product/workflows/delete-collections.ts +++ b/packages/core/core-flows/src/product/workflows/delete-collections.ts @@ -9,11 +9,39 @@ import { import { emitEventStep } from "../../common" import { deleteCollectionsStep } from "../steps" -export type DeleteCollectionsWorkflowInput = { ids: string[] } +/** + * The data to delete one or more product collections. + */ +export type DeleteCollectionsWorkflowInput = { + /** + * The IDs of the collections to delete. + */ + ids: string[] +} export const deleteCollectionsWorkflowId = "delete-collections" /** - * This workflow deletes one or more collection. + * This workflow deletes one or more product collections. It's used by the + * [Delete Product Collection Admin API Route](https://docs.medusajs.com/api/admin#collections_deletecollectionsid). + * + * This workflow has a hook that allows you to perform custom actions after the product collections are deleted. For example, + * you can delete custom records linked to the product colleciton. + * + * You can also use this workflow within your own custom workflows, allowing you to wrap custom logic around product-collection deletion. + * + * @example + * const { result } = await deleteCollectionsWorkflow(container) + * .run({ + * input: { + * ids: ["pcol_123"], + * } + * }) + * + * @summary + * + * Delete one or more product collection. + * + * @property hooks.collectionsDeleted - This hook is executed after the collections are deleted. You can consume this hook to perform custom actions on the deleted collections. */ export const deleteCollectionsWorkflow = createWorkflow( deleteCollectionsWorkflowId, diff --git a/packages/core/core-flows/src/product/workflows/delete-product-options.ts b/packages/core/core-flows/src/product/workflows/delete-product-options.ts index 8bd7ec13067eb..df87f0ac64320 100644 --- a/packages/core/core-flows/src/product/workflows/delete-product-options.ts +++ b/packages/core/core-flows/src/product/workflows/delete-product-options.ts @@ -9,11 +9,39 @@ import { import { emitEventStep } from "../../common/steps/emit-event" import { deleteProductOptionsStep } from "../steps" -export type DeleteProductOptionsWorkflowInput = { ids: string[] } +/** + * The data to delete one or more product options. + */ +export type DeleteProductOptionsWorkflowInput = { + /** + * The IDs of the options to delete. + */ + ids: string[] +} export const deleteProductOptionsWorkflowId = "delete-product-options" /** - * This workflow deletes one or more product options. + * This workflow deletes one or more product options. It's used by the + * [Delete Product Option Admin API Route](https://docs.medusajs.com/api/admin#products_deleteproductsidoptionsoption_id). + * + * This workflow has a hook that allows you to perform custom actions after the product options are deleted. For example, + * you can delete custom records linked to the product colleciton. + * + * You can also use this workflow within your own custom workflows, allowing you to wrap custom logic around product-option deletion. + * + * @example + * const { result } = await deleteProductOptionsWorkflow(container) + * .run({ + * input: { + * ids: ["poption_123"], + * } + * }) + * + * @summary + * + * Delete one or more product option. + * + * @property hooks.productOptionsDeleted - This hook is executed after the options are deleted. You can consume this hook to perform custom actions on the deleted options. */ export const deleteProductOptionsWorkflow = createWorkflow( deleteProductOptionsWorkflowId, diff --git a/packages/core/core-flows/src/product/workflows/delete-product-tags.ts b/packages/core/core-flows/src/product/workflows/delete-product-tags.ts index 5728697e22a94..00d1661ce9c96 100644 --- a/packages/core/core-flows/src/product/workflows/delete-product-tags.ts +++ b/packages/core/core-flows/src/product/workflows/delete-product-tags.ts @@ -9,11 +9,39 @@ import { import { emitEventStep } from "../../common/steps/emit-event" import { deleteProductTagsStep } from "../steps" -export type DeleteProductTagsWorkflowInput = { ids: string[] } +/** + * The data to delete one or more product tags. + */ +export type DeleteProductTagsWorkflowInput = { + /** + * The IDs of the tags to delete. + */ + ids: string[] +} export const deleteProductTagsWorkflowId = "delete-product-tags" /** - * This workflow deletes one or more product tags. + * This workflow deletes one or more product tags. It's used by the + * [Delete Product Tags Admin API Route](https://docs.medusajs.com/api/admin#product-tags_deleteproducttagsid). + * + * This workflow has a hook that allows you to perform custom actions after the product tags are deleted. For example, + * you can delete custom records linked to the product tags. + * + * You can also use this workflow within your own custom workflows, allowing you to wrap custom logic around product-tag deletion. + * + * @example + * const { result } = await deleteProductTagsWorkflow(container) + * .run({ + * input: { + * ids: ["ptag_123"], + * } + * }) + * + * @summary + * + * Delete one or more product tags. + * + * @property hooks.productTagsDeleted - This hook is executed after the tags are deleted. You can consume this hook to perform custom actions on the deleted tags. */ export const deleteProductTagsWorkflow = createWorkflow( deleteProductTagsWorkflowId, diff --git a/packages/core/core-flows/src/product/workflows/delete-product-types.ts b/packages/core/core-flows/src/product/workflows/delete-product-types.ts index 9eafecc0ccbad..95698d7d40e6f 100644 --- a/packages/core/core-flows/src/product/workflows/delete-product-types.ts +++ b/packages/core/core-flows/src/product/workflows/delete-product-types.ts @@ -9,11 +9,39 @@ import { import { emitEventStep } from "../../common/steps/emit-event" import { deleteProductTypesStep } from "../steps" -export type DeleteProductTypesWorkflowInput = { ids: string[] } +/** + * The data to delete one or more product types. + */ +export type DeleteProductTypesWorkflowInput = { + /** + * The IDs of the types to delete. + */ + ids: string[] +} export const deleteProductTypesWorkflowId = "delete-product-types" /** - * This workflow deletes one or more product types. + * This workflow deletes one or more product types. It's used by the + * [Delete Product Types Admin API Route](https://docs.medusajs.com/api/admin#product-types_deleteproducttypesid). + * + * This workflow has a hook that allows you to perform custom actions after the product types are deleted. For example, + * you can delete custom records linked to the product types. + * + * You can also use this workflow within your own custom workflows, allowing you to wrap custom logic around product-type deletion. + * + * @example + * const { result } = await deleteProductTypesWorkflow(container) + * .run({ + * input: { + * ids: ["ptyp_123"], + * } + * }) + * + * @summary + * + * Delete one or more product types. + * + * @property hooks.productTypesDeleted - This hook is executed after the types are deleted. You can consume this hook to perform custom actions on the deleted types. */ export const deleteProductTypesWorkflow = createWorkflow( deleteProductTypesWorkflowId, diff --git a/packages/core/core-flows/src/product/workflows/delete-product-variants.ts b/packages/core/core-flows/src/product/workflows/delete-product-variants.ts index 1b0cf862637cd..2e0572b706b84 100644 --- a/packages/core/core-flows/src/product/workflows/delete-product-variants.ts +++ b/packages/core/core-flows/src/product/workflows/delete-product-variants.ts @@ -17,11 +17,39 @@ import { import { deleteProductVariantsStep } from "../steps" import { deleteInventoryItemWorkflow } from "../../inventory" -export type DeleteProductVariantsWorkflowInput = { ids: string[] } +/** + * The data to delete one or more product variants. + */ +export type DeleteProductVariantsWorkflowInput = { + /** + * The IDs of the variants to delete. + */ + ids: string[] +} export const deleteProductVariantsWorkflowId = "delete-product-variants" /** - * This workflow deletes one or more product variants. + * This workflow deletes one or more product variants. It's used by the + * [Delete Product Variants Admin API Route](https://docs.medusajs.com/api/admin#products_deleteproductsidvariantsvariant_id). + * + * This workflow has a hook that allows you to perform custom actions after the product variants are deleted. For example, + * you can delete custom records linked to the product variants. + * + * You can also use this workflow within your own custom workflows, allowing you to wrap custom logic around product-variant deletion. + * + * @example + * const { result } = await deleteProductVariantsWorkflow(container) + * .run({ + * input: { + * ids: ["variant_123"], + * } + * }) + * + * @summary + * + * Delete one or more product variants. + * + * @property hooks.productVariantsDeleted - This hook is executed after the variants are deleted. You can consume this hook to perform custom actions on the deleted variants. */ export const deleteProductVariantsWorkflow = createWorkflow( deleteProductVariantsWorkflowId, diff --git a/packages/core/core-flows/src/product/workflows/delete-products.ts b/packages/core/core-flows/src/product/workflows/delete-products.ts index 78c72972980a5..0c57e3abd1bb9 100644 --- a/packages/core/core-flows/src/product/workflows/delete-products.ts +++ b/packages/core/core-flows/src/product/workflows/delete-products.ts @@ -16,11 +16,39 @@ import { deleteProductsStep } from "../steps/delete-products" import { getProductsStep } from "../steps/get-products" import { deleteInventoryItemWorkflow } from "../../inventory" -export type DeleteProductsWorkflowInput = { ids: string[] } +/** + * The data to delete one or more products. + */ +export type DeleteProductsWorkflowInput = { + /** + * The IDs of the products to delete. + */ + ids: string[] +} export const deleteProductsWorkflowId = "delete-products" /** - * This workflow deletes one or more products. + * This workflow deletes one or more products. It's used by the + * [Delete Products Admin API Route](https://docs.medusajs.com/api/admin#products_deleteproductsid). + * + * This workflow has a hook that allows you to perform custom actions after the products are deleted. For example, + * you can delete custom records linked to the products. + * + * You can also use this workflow within your own custom workflows, allowing you to wrap custom logic around product deletion. + * + * @example + * const { result } = await deleteProductsWorkflow(container) + * .run({ + * input: { + * ids: ["product_123"], + * } + * }) + * + * @summary + * + * Delete one or more products. + * + * @property hooks.productsDeleted - This hook is executed after the products are deleted. You can consume this hook to perform custom actions on the deleted products. */ export const deleteProductsWorkflow = createWorkflow( deleteProductsWorkflowId, diff --git a/packages/core/core-flows/src/product/workflows/export-products.ts b/packages/core/core-flows/src/product/workflows/export-products.ts index 1058253e18f33..6739c3ac8fe84 100644 --- a/packages/core/core-flows/src/product/workflows/export-products.ts +++ b/packages/core/core-flows/src/product/workflows/export-products.ts @@ -10,7 +10,45 @@ import { notifyOnFailureStep, sendNotificationsStep } from "../../notification" export const exportProductsWorkflowId = "export-products" /** - * This workflow exports products matching the specified filters. + * This workflow exports products matching the specified filters. It's used by the + * [Export Products Admin API Route](https://docs.medusajs.com/api/admin#products_postproductsexport). + * + * :::note + * + * This workflow doesn't return the exported products. Instead, it sends a notification to the admin + * users that they can download the exported products. Learn more in the [API Reference](https://docs.medusajs.com/api/admin#products_postproductsexport). + * + * ::: + * + * @example + * To export all products: + * + * ```ts + * const { result } = await exportProductsWorkflow(container) + * .run({ + * input: { + * select: ["*"], + * } + * }) + * ``` + * + * To export products matching a criteria: + * + * ```ts + * const { result } = await exportProductsWorkflow(container) + * .run({ + * input: { + * select: ["*"], + * filter: { + * collection_id: "pcol_123" + * } + * } + * }) + * ``` + * + * @summary + * + * Export products with filtering capabilities. */ export const exportProductsWorkflow = createWorkflow( exportProductsWorkflowId, diff --git a/packages/core/core-flows/src/product/workflows/import-products.ts b/packages/core/core-flows/src/product/workflows/import-products.ts index 87c1ff2913e5b..8d887d9058e9d 100644 --- a/packages/core/core-flows/src/product/workflows/import-products.ts +++ b/packages/core/core-flows/src/product/workflows/import-products.ts @@ -15,7 +15,79 @@ import { batchProductsWorkflow } from "./batch-products" export const importProductsWorkflowId = "import-products" /** - * This workflow imports products from a CSV file. + * This workflow starts a product import from a CSV file in the background. It's used by the + * [Import Products Admin API Route](https://docs.medusajs.com/api/admin#products_postproductsimport). + * + * You can use this workflow within your custom workflows, allowing you to wrap custom logic around product import. + * For example, you can import products from another system. + * + * The workflow only starts the import, but you'll have to confirm it using the [Workflow Engine](https://docs.medusajs.com/resources/architectural-modules/workflow-engine). + * The below example shows how to confirm the import. + * + * @example + * To start the import of a CSV file: + * + * ```ts + * const { result, transaction: { transactionId } } = await importProductsWorkflow(container) + * .run({ + * input: { + * // example CSV content + * fileContent: "title,description\nShirt,This is a shirt", + * filename: "products.csv", + * } + * }) + * ``` + * + * Notice that the workflow returns a `transaction.transactionId`. You'll use this ID to confirm the import afterwards. + * + * You confirm the import using the [Workflow Engine](https://docs.medusajs.com/resources/architectural-modules/workflow-engine). + * For example, in an API route: + * + * ```ts workflow={false} + * import { + * AuthenticatedMedusaRequest, + * MedusaResponse, + * } from "@medusajs/framework/http" + * import { + * importProductsWorkflowId, + * waitConfirmationProductImportStepId, + * } from "@medusajs/core-flows" + * import { IWorkflowEngineService } from "@medusajs/framework/types" + * import { Modules, TransactionHandlerType } from "@medusajs/framework/utils" + * import { StepResponse } from "@medusajs/framework/workflows-sdk" + * + * export const POST = async ( + * req: AuthenticatedMedusaRequest, + * res: MedusaResponse + * ) => { + * const workflowEngineService: IWorkflowEngineService = req.scope.resolve( + * Modules.WORKFLOW_ENGINE + * ) + * const transactionId = req.params.transaction_id + * + * await workflowEngineService.setStepSuccess({ + * idempotencyKey: { + * action: TransactionHandlerType.INVOKE, + * transactionId, + * stepId: waitConfirmationProductImportStepId, + * workflowId: importProductsWorkflowId, + * }, + * stepResponse: new StepResponse(true), + * }) + * + * res.status(202).json({}) + * } + * ``` + * + * :::tip + * + * This example API route uses the same implementation as the [Confirm Product Import Admin API Route](https://docs.medusajs.com/api/admin#products_postproductsimporttransaction_idconfirm). + * + * ::: + * + * @summary + * + * Import products from a CSV file. */ export const importProductsWorkflow = createWorkflow( importProductsWorkflowId, diff --git a/packages/core/core-flows/src/product/workflows/update-collections.ts b/packages/core/core-flows/src/product/workflows/update-collections.ts index 62fe36b81083a..0c977cf45985a 100644 --- a/packages/core/core-flows/src/product/workflows/update-collections.ts +++ b/packages/core/core-flows/src/product/workflows/update-collections.ts @@ -10,14 +10,51 @@ import { import { emitEventStep } from "../../common" import { updateCollectionsStep } from "../steps" +/** + * The data to update one or more product collections, along with custom data that's passed to the workflow's hooks. + */ export type UpdateCollectionsWorkflowInput = { + /** + * The filters to select the collections to update. + */ selector: ProductTypes.FilterableProductCollectionProps + /** + * The data to update the collections with. + */ update: ProductTypes.UpdateProductCollectionDTO } & AdditionalData export const updateCollectionsWorkflowId = "update-collections" /** - * This workflow updates collections matching the specified filters. + * This workflow updates one or more collections. It's used by the + * [Create Collection Admin API Route](https://docs.medusajs.com/api/admin#collections_postcollectionsid). + * + * This workflow has a hook that allows you to perform custom actions on the updated collections. For example, you can pass under `additional_data` custom data that + * allows you to update custom data models linked to the product collections. + * + * You can also use this workflow within your own custom workflows, allowing you to wrap custom logic around product-collection update. + * + * @example + * const { result } = await updateCollectionsWorkflow(container) + * .run({ + * input: { + * selector: { + * id: "pcol_123" + * }, + * update: { + * title: "Summer Collection" + * }, + * additional_data: { + * erp_id: "123" + * } + * } + * }) + * + * @summary + * + * Update one or more product collections. + * + * @property hooks.collectionsUpdated - This hook is executed after the collections are updated. You can consume this hook to perform custom actions on the updated collections. */ export const updateCollectionsWorkflow = createWorkflow( updateCollectionsWorkflowId, diff --git a/packages/core/core-flows/src/product/workflows/update-product-options.ts b/packages/core/core-flows/src/product/workflows/update-product-options.ts index f4aec3f8f4ab1..c3226f2f89028 100644 --- a/packages/core/core-flows/src/product/workflows/update-product-options.ts +++ b/packages/core/core-flows/src/product/workflows/update-product-options.ts @@ -31,7 +31,7 @@ export const updateProductOptionsWorkflowId = "update-product-options" * This workflow has a hook that allows you to perform custom actions on the updated product options. For example, you can pass under `additional_data` custom data that * allows you to update custom data models linked to the product options. * - * You can also use this workflow within your own custom workflows, allowing you to wrap custom logic around product-option update. + * You can also use this workflow within your customizations or your own custom workflows, allowing you to wrap custom logic around product-option update. * * @example * const { result } = await updateProductOptionsWorkflow(container) diff --git a/packages/core/core-flows/src/product/workflows/update-product-tags.ts b/packages/core/core-flows/src/product/workflows/update-product-tags.ts index c665f28e4f431..36ba4b6af8752 100644 --- a/packages/core/core-flows/src/product/workflows/update-product-tags.ts +++ b/packages/core/core-flows/src/product/workflows/update-product-tags.ts @@ -10,14 +10,51 @@ import { import { emitEventStep } from "../../common/steps/emit-event" import { updateProductTagsStep } from "../steps" +/** + * The data to update one or more product tags, along with custom data that's passed to the workflow's hooks. + */ export type UpdateProductTagsWorkflowInput = { + /** + * The filters to select the product tags to update. + */ selector: ProductTypes.FilterableProductTypeProps + /** + * The data to update in the product tags. + */ update: ProductTypes.UpdateProductTypeDTO } & AdditionalData export const updateProductTagsWorkflowId = "update-product-tags" /** - * This workflow updates product tags matching the specified filters. + * This workflow updates one or more product tags. It's used by the + * [Update Product Tag Admin API Route](https://docs.medusajs.com/api/admin#product-tags_postproducttagsid). + * + * This workflow has a hook that allows you to perform custom actions on the updated product tags. For example, you can pass under `additional_data` custom data that + * allows you to update custom data models linked to the product tags. + * + * You can also use this workflow within your own custom workflows, allowing you to wrap custom logic around product-tag updates. + * + * @example + * const { result } = await updateProductTagsWorkflow(container) + * .run({ + * input: { + * selector: { + * id: "pcol_123" + * }, + * update: { + * value: "clothing" + * }, + * additional_data: { + * erp_id: "123" + * } + * } + * }) + * + * @summary + * + * Update one or more product tags. + * + * @property hooks.productTagsUpdated - This hook is executed after the product tags are updated. You can consume this hook to perform custom actions on the updated product tags. */ export const updateProductTagsWorkflow = createWorkflow( updateProductTagsWorkflowId, diff --git a/packages/core/core-flows/src/product/workflows/update-product-types.ts b/packages/core/core-flows/src/product/workflows/update-product-types.ts index d217424cc7afc..494e10cd20594 100644 --- a/packages/core/core-flows/src/product/workflows/update-product-types.ts +++ b/packages/core/core-flows/src/product/workflows/update-product-types.ts @@ -10,14 +10,51 @@ import { import { emitEventStep } from "../../common/steps/emit-event" import { updateProductTypesStep } from "../steps" +/** + * The data to update one or more product types, along with custom data that's passed to the workflow's hooks. + */ type UpdateProductTypesWorkflowInput = { + /** + * The filters to select the product types to update. + */ selector: ProductTypes.FilterableProductTypeProps + /** + * The data to update in the product types. + */ update: ProductTypes.UpdateProductTypeDTO } & AdditionalData export const updateProductTypesWorkflowId = "update-product-types" /** - * This workflow updates product types matching the specified filters. + * This workflow updates one or more product types. It's used by the + * [Update Product Type Admin API Route](https://docs.medusajs.com/api/admin#product-types_postproducttypesid). + * + * This workflow has a hook that allows you to perform custom actions on the updated product types. For example, you can pass under `additional_data` custom data that + * allows you to update custom data models linked to the product types. + * + * You can also use this workflow within your own custom workflows, allowing you to wrap custom logic around product-type updates. + * + * @example + * const { result } = await updateProductTypesWorkflow(container) + * .run({ + * input: { + * selector: { + * id: "ptyp_123" + * }, + * update: { + * value: "clothing" + * }, + * additional_data: { + * erp_id: "123" + * } + * } + * }) + * + * @summary + * + * Update one or more product types. + * + * @property hooks.productTypesUpdated - This hook is executed after the product types are updated. You can consume this hook to perform custom actions on the updated product types. */ export const updateProductTypesWorkflow = createWorkflow( updateProductTypesWorkflowId, diff --git a/packages/core/core-flows/src/product/workflows/update-product-variants.ts b/packages/core/core-flows/src/product/workflows/update-product-variants.ts index cb17e0e051225..dd162c7a626a7 100644 --- a/packages/core/core-flows/src/product/workflows/update-product-variants.ts +++ b/packages/core/core-flows/src/product/workflows/update-product-variants.ts @@ -54,7 +54,7 @@ export const updateProductVariantsWorkflowId = "update-product-variants" * This workflow has a hook that allows you to perform custom actions on the updated product variants. For example, you can pass under `additional_data` custom data that * allows you to update custom data models linked to the product variants. * - * You can also use this workflow within your own custom workflows, allowing you to wrap custom logic around product-variant update. + * You can also use this workflow within your customizations or your own custom workflows, allowing you to wrap custom logic around product-variant update. * * @example * To update product variants by their IDs: diff --git a/packages/core/core-flows/src/product/workflows/update-products.ts b/packages/core/core-flows/src/product/workflows/update-products.ts index 8ed2a6ff7d5de..e92d86fbdd595 100644 --- a/packages/core/core-flows/src/product/workflows/update-products.ts +++ b/packages/core/core-flows/src/product/workflows/update-products.ts @@ -250,7 +250,7 @@ export const updateProductsWorkflowId = "update-products" * This workflow has a hook that allows you to perform custom actions on the updated products. For example, you can pass under `additional_data` custom data that * allows you to update custom data models linked to the products. * - * You can also use this workflow within your own custom workflows, allowing you to wrap custom logic around product update. + * You can also use this workflow within your customizations or your own custom workflows, allowing you to wrap custom logic around product update. * * @example * To update products by their IDs: diff --git a/packages/core/core-flows/src/product/workflows/upsert-variant-prices.ts b/packages/core/core-flows/src/product/workflows/upsert-variant-prices.ts index 26b82b5079c5e..74aa8af7c092f 100644 --- a/packages/core/core-flows/src/product/workflows/upsert-variant-prices.ts +++ b/packages/core/core-flows/src/product/workflows/upsert-variant-prices.ts @@ -13,18 +13,69 @@ import { removeRemoteLinkStep, useRemoteQueryStep } from "../../common" import { createPriceSetsStep, updatePriceSetsStep } from "../../pricing" import { createVariantPricingLinkStep } from "../steps" +/** + * The data to create, update, or remove variants' prices. + */ export type UpsertVariantPricesWorkflowInput = { + /** + * The variants to create or update prices for. + */ variantPrices: { + /** + * The ID of the variant to create or update prices for. + */ variant_id: string + /** + * The ID of the product the variant belongs to. + */ product_id: string + /** + * The prices to create or update for the variant. + */ prices?: (CreatePricesDTO | UpdatePricesDTO)[] }[] + /** + * The IDs of the variants to remove all their prices. + */ previousVariantIds: string[] } export const upsertVariantPricesWorkflowId = "upsert-variant-prices" /** - * This workflow creates or updates variants' prices. + * This workflow creates, updates, or removes variants' prices. It's used by the {@link updateProductsWorkflow} + * when updating a variant's prices. + * + * You can use this workflow within your own custom workflows to manage the prices of a variant. + * + * @example + * const { result } = await upsertVariantPricesWorkflow(container) + * .run({ + * input: { + * variantPrices: [ + * { + * variant_id: "variant_123", + * product_id: "prod_123", + * prices: [ + * { + * amount: 10, + * currency_code: "usd", + * }, + * { + * id: "price_123", + * amount: 20, + * } + * ] + * } + * ], + * // these are variants to remove all their prices + * // typically used when a variant is deleted. + * previousVariantIds: ["variant_321"] + * } + * }) + * + * @summary + * + * Create, update, or remove variants' prices. */ export const upsertVariantPricesWorkflow = createWorkflow( upsertVariantPricesWorkflowId, diff --git a/packages/core/core-flows/src/promotion/workflows/create-campaigns.ts b/packages/core/core-flows/src/promotion/workflows/create-campaigns.ts index b9e0f262a8ead..f1de5fb3b890d 100644 --- a/packages/core/core-flows/src/promotion/workflows/create-campaigns.ts +++ b/packages/core/core-flows/src/promotion/workflows/create-campaigns.ts @@ -23,7 +23,7 @@ export const createCampaignsWorkflowId = "create-campaigns" * This workflow has a hook that allows you to perform custom actions on the created campaigns. For example, you can pass under `additional_data` custom data that * allows you to create custom data models linked to the campaigns. * - * You can also use this workflow within your own custom workflows, allowing you to wrap custom logic around creating campaigns. + * You can also use this workflow within your customizations or your own custom workflows, allowing you to wrap custom logic around creating campaigns. * * @example * const { result } = await createCampaignsWorkflow(container) diff --git a/packages/core/core-flows/src/promotion/workflows/create-promotions.ts b/packages/core/core-flows/src/promotion/workflows/create-promotions.ts index 0ef246148be6f..da94ef7738692 100644 --- a/packages/core/core-flows/src/promotion/workflows/create-promotions.ts +++ b/packages/core/core-flows/src/promotion/workflows/create-promotions.ts @@ -23,7 +23,7 @@ export const createPromotionsWorkflowId = "create-promotions" * This workflow has a hook that allows you to perform custom actions on the created promotion. For example, you can pass under `additional_data` custom data that * allows you to create custom data models linked to the promotions. * - * You can also use this workflow within your own custom workflows, allowing you to wrap custom logic around creating promotions. + * You can also use this workflow within your customizations or your own custom workflows, allowing you to wrap custom logic around creating promotions. * * @example * const { result } = await createPromotionsWorkflow(container) diff --git a/packages/core/core-flows/src/promotion/workflows/update-campaigns.ts b/packages/core/core-flows/src/promotion/workflows/update-campaigns.ts index 9848e4b7af6c1..f0f28fc97e4ff 100644 --- a/packages/core/core-flows/src/promotion/workflows/update-campaigns.ts +++ b/packages/core/core-flows/src/promotion/workflows/update-campaigns.ts @@ -23,7 +23,7 @@ export const updateCampaignsWorkflowId = "update-campaigns" * This workflow has a hook that allows you to perform custom actions on the updated campaigns. For example, you can pass under `additional_data` custom data that * allows you to update custom data models linked to the campaigns. * - * You can also use this workflow within your own custom workflows, allowing you to wrap custom logic around updating campaigns. + * You can also use this workflow within your customizations or your own custom workflows, allowing you to wrap custom logic around updating campaigns. * * @example * const { result } = await updateCampaignsWorkflow(container) diff --git a/packages/core/core-flows/src/promotion/workflows/update-promotions.ts b/packages/core/core-flows/src/promotion/workflows/update-promotions.ts index 4950675330a7f..107081640f57c 100644 --- a/packages/core/core-flows/src/promotion/workflows/update-promotions.ts +++ b/packages/core/core-flows/src/promotion/workflows/update-promotions.ts @@ -23,7 +23,7 @@ export const updatePromotionsWorkflowId = "update-promotions" * This workflow has a hook that allows you to perform custom actions on the updated promotion. For example, you can pass under `additional_data` custom data that * allows you to update custom data models linked to the promotions. * - * You can also use this workflow within your own custom workflows, allowing you to wrap custom logic around updating promotions. + * You can also use this workflow within your customizations or your own custom workflows, allowing you to wrap custom logic around updating promotions. * * @example * const { result } = await updatePromotionsWorkflow(container) diff --git a/packages/core/framework/package.json b/packages/core/framework/package.json index fc42cc1835625..038a16ec82b4a 100644 --- a/packages/core/framework/package.json +++ b/packages/core/framework/package.json @@ -31,7 +31,8 @@ "./orchestration": "./dist/orchestration/index.js", "./workflows-sdk": "./dist/workflows-sdk/index.js", "./workflows-sdk/composer": "./dist/workflows-sdk/composer.js", - "./modules-sdk": "./dist/modules-sdk/index.js" + "./modules-sdk": "./dist/modules-sdk/index.js", + "./migrations": "./dist/migrations/index.js" }, "engines": { "node": ">=20" diff --git a/packages/core/framework/src/index.ts b/packages/core/framework/src/index.ts index 3d78406d5d3f5..05b58590fe4f3 100644 --- a/packages/core/framework/src/index.ts +++ b/packages/core/framework/src/index.ts @@ -11,6 +11,7 @@ export * from "./subscribers" export * from "./workflows" export * from "./telemetry" export * from "./zod" +export * from "./migrations" export const MEDUSA_CLI_PATH = require.resolve("@medusajs/cli") diff --git a/packages/core/framework/src/migrations/__tests__/run-migration-scripts.spec.ts b/packages/core/framework/src/migrations/__tests__/run-migration-scripts.spec.ts new file mode 100644 index 0000000000000..b3ba38b5306f6 --- /dev/null +++ b/packages/core/framework/src/migrations/__tests__/run-migration-scripts.spec.ts @@ -0,0 +1,172 @@ +import { MedusaContainer } from "@medusajs/types" +import { MigrationScriptsMigrator } from "../run-migration-scripts" +import { jest } from "@jest/globals" +import path from "path" +import { ContainerRegistrationKeys, Modules } from "@medusajs/utils" + +const mockPgConnection = { + raw: jest.fn(), +} + +const mockLockService = { + acquire: jest.fn(), + release: jest.fn(), +} + +const mockContainer = { + resolve: (key: string) => { + if (key === ContainerRegistrationKeys.PG_CONNECTION) { + return mockPgConnection + } + if (key === Modules.LOCKING) { + return mockLockService + } + + throw new Error(`Unknown key: ${key}`) + }, +} as unknown as MedusaContainer + +describe("MigrationScriptsMigrator", () => { + let migrator: MigrationScriptsMigrator + + beforeEach(() => { + jest.clearAllMocks() + migrator = new MigrationScriptsMigrator({ container: mockContainer }) + // @ts-ignore + migrator.pgConnection = mockPgConnection + }) + + describe("run", () => { + it("should successfully run migration scripts", async () => { + const mockScript = jest.fn() + const scriptPath = "/path/to/migration.ts" + + jest + .spyOn(migrator as any, "getPendingMigrations") + .mockResolvedValue([scriptPath]) + jest + .spyOn(migrator as any, "insertMigration") + .mockResolvedValue(undefined) + jest + .spyOn(migrator as any, "trackDuration") + .mockReturnValue({ getSeconds: () => 1 }) + + jest.mock( + scriptPath, + () => ({ + default: mockScript, + }), + { virtual: true } + ) + + await migrator.run([scriptPath]) + + expect(mockScript).toHaveBeenCalled() + + expect(mockPgConnection.raw).toHaveBeenCalledWith( + expect.stringContaining("UPDATE script_migrations"), + [path.basename(scriptPath)] + ) + expect(migrator["insertMigration"]).toHaveBeenCalledWith([ + { script_name: `'${path.basename(scriptPath)}'` }, + ]) + }) + + it("should handle failed migrations by cleaning up", async () => { + const scriptPath = "/path/to/failing-migration.ts" + const error = new Error("Migration failed") + + jest + .spyOn(migrator as any, "getPendingMigrations") + .mockResolvedValue([scriptPath]) + jest + .spyOn(migrator as any, "insertMigration") + .mockResolvedValue(undefined) + jest + .spyOn(migrator as any, "trackDuration") + .mockReturnValue({ getSeconds: () => 1 }) + + const mockFailingScript = jest.fn().mockRejectedValue(error as never) + jest.mock( + scriptPath, + () => ({ + default: mockFailingScript, + }), + { virtual: true } + ) + + await expect(migrator.run([scriptPath])).rejects.toThrow( + "Migration failed" + ) + + expect(mockPgConnection.raw).toHaveBeenCalledWith( + expect.stringContaining("DELETE FROM script_migrations"), + [path.basename(scriptPath)] + ) + }) + + it("should skip migration when unique constraint error occurs", async () => { + const scriptPath = "/path/to/migration.ts" + const uniqueError = new Error("Unique constraint violation") + ;(uniqueError as any).constraint = "idx_script_name_unique" + + jest + .spyOn(migrator as any, "getPendingMigrations") + .mockResolvedValue([scriptPath]) + jest + .spyOn(migrator as any, "insertMigration") + .mockRejectedValue(uniqueError) + jest + .spyOn(migrator as any, "trackDuration") + .mockReturnValue({ getSeconds: () => 1 }) + + const mockScript = jest.fn() + jest.mock( + scriptPath, + () => ({ + default: mockScript, + }), + { virtual: true } + ) + + await migrator.run([scriptPath]) + + expect(mockScript).not.toHaveBeenCalled() + expect(mockPgConnection.raw).not.toHaveBeenCalledWith( + expect.stringContaining("UPDATE script_migrations") + ) + }) + }) + + describe("getPendingMigrations", () => { + it("should return only non-executed migrations", async () => { + const executedMigration = "executed.ts" + const pendingMigration = "pending.ts" + + jest + .spyOn(migrator as any, "getExecutedMigrations") + .mockResolvedValue([{ script_name: executedMigration }]) + jest + .spyOn(migrator as any, "loadMigrationFiles") + .mockResolvedValue([ + `/path/to/${executedMigration}`, + `/path/to/${pendingMigration}`, + ]) + + const result = await migrator.getPendingMigrations(["/path/to"]) + + expect(result).toHaveLength(1) + expect(result[0]).toContain(pendingMigration) + }) + }) + + describe("createMigrationTable", () => { + it("should create migration table if it doesn't exist", async () => { + await (migrator as any).createMigrationTable() + + expect(mockPgConnection.raw).toHaveBeenCalledWith( + expect.stringContaining("CREATE TABLE IF NOT EXISTS script_migrations") + ) + }) + }) +}) diff --git a/packages/core/framework/src/migrations/index.ts b/packages/core/framework/src/migrations/index.ts new file mode 100644 index 0000000000000..de4e16e605057 --- /dev/null +++ b/packages/core/framework/src/migrations/index.ts @@ -0,0 +1,2 @@ +export * from "./migrator" +export * from "./run-migration-scripts" diff --git a/packages/core/framework/src/migrations/migrator.ts b/packages/core/framework/src/migrations/migrator.ts new file mode 100644 index 0000000000000..76d3a04806d01 --- /dev/null +++ b/packages/core/framework/src/migrations/migrator.ts @@ -0,0 +1,158 @@ +import { join } from "path" +import { glob } from "glob" +import { logger } from "../logger" +import { MedusaContainer } from "@medusajs/types" +import { ContainerRegistrationKeys } from "../utils" +import { Knex } from "@mikro-orm/knex" + +export abstract class Migrator { + protected abstract migration_table_name: string + + protected container: MedusaContainer + protected pgConnection: Knex + + #alreadyLoadedPaths: Map = new Map() + + constructor({ container }: { container: MedusaContainer }) { + this.container = container + this.pgConnection = this.container.resolve( + ContainerRegistrationKeys.PG_CONNECTION + ) + } + + /** + * Util to track duration using hrtime + */ + protected trackDuration() { + const startTime = process.hrtime() + return { + getSeconds() { + const duration = process.hrtime(startTime) + return (duration[0] + duration[1] / 1e9).toFixed(2) + }, + } + } + + async ensureDatabase(): Promise { + const pgConnection = this.container.resolve( + ContainerRegistrationKeys.PG_CONNECTION + ) + + try { + await pgConnection.raw("SELECT 1 + 1;") + } catch (error) { + if (error.code === "3D000") { + logger.error( + `Cannot run migrations. ${error.message.replace("error: ", "")}` + ) + logger.info(`Run command "db:create" to create the database`) + } else { + logger.error(error) + } + throw error + } + } + + async ensureMigrationsTable(): Promise { + try { + // Check if table exists + const tableExists = await this.pgConnection.raw(` + SELECT EXISTS ( + SELECT FROM information_schema.tables + WHERE table_schema = 'public' + AND table_name = '${this.migration_table_name}' + ); + `) + + if (!tableExists.rows[0].exists) { + logger.info( + `Creating migrations table '${this.migration_table_name}'...` + ) + await this.createMigrationTable() + logger.info("Migrations table created successfully") + } + } catch (error) { + logger.error("Failed to ensure migrations table exists:", error) + throw error + } + } + + async getExecutedMigrations(): Promise<{ script_name: string }[]> { + try { + const result = await this.pgConnection.raw( + `SELECT * FROM ${this.migration_table_name}` + ) + return result.rows + } catch (error) { + logger.error("Failed to get executed migrations:", error) + throw error + } + } + + async insertMigration(records: Record[]): Promise { + try { + const values = records.map((record) => Object.values(record)) + const columns = Object.keys(records[0]) + + await this.pgConnection.raw( + `INSERT INTO ${this.migration_table_name} (${columns.join( + ", " + )}) VALUES (${new Array(values.length).fill("?").join(",")})`, + values + ) + } catch (error) { + logger.error( + `Failed to update migration table '${this.migration_table_name}':`, + error + ) + throw error + } + } + + /** + * Load migration files from the given paths + * + * @param paths - The paths to load migration files from + * @param options - The options for loading migration files + * @param options.force - Whether to force loading migration files even if they have already been loaded + * @returns The loaded migration file paths + */ + async loadMigrationFiles( + paths: string[], + { force }: { force?: boolean } = { force: false } + ): Promise { + const allScripts: string[] = [] + + for (const basePath of paths) { + if (!force && this.#alreadyLoadedPaths.has(basePath)) { + allScripts.push(...this.#alreadyLoadedPaths.get(basePath)) + continue + } + + try { + const scriptFiles = glob.sync("*.{js,ts}", { + cwd: basePath, + ignore: ["**/index.{js,ts}"], + }) + + if (!scriptFiles?.length) { + continue + } + + const filePaths = scriptFiles.map((script) => join(basePath, script)) + this.#alreadyLoadedPaths.set(basePath, filePaths) + + allScripts.push(...filePaths) + } catch (error) { + logger.error(`Failed to load migration files from ${basePath}:`, error) + throw error + } + } + + return allScripts + } + + protected abstract createMigrationTable(): Promise + abstract run(...args: any[]): Promise + abstract getPendingMigrations(migrationPaths: string[]): Promise +} diff --git a/packages/core/framework/src/migrations/run-migration-scripts.ts b/packages/core/framework/src/migrations/run-migration-scripts.ts new file mode 100644 index 0000000000000..ff88a070382c6 --- /dev/null +++ b/packages/core/framework/src/migrations/run-migration-scripts.ts @@ -0,0 +1,113 @@ +import { MedusaContainer } from "@medusajs/types" +import { dynamicImport, Modules } from "@medusajs/utils" +import { basename } from "path" +import { logger } from "../logger" +import { Migrator } from "./migrator" + +export class MigrationScriptsMigrator extends Migrator { + protected migration_table_name = "script_migrations" + + constructor({ container }: { container: MedusaContainer }) { + super({ container }) + } + + /** + * Run the migration scripts + * @param paths - The paths from which to load the scripts + */ + async run(paths: string[]): Promise { + const lockService = this.container.resolve(Modules.LOCKING) + + const lockKey = "migration-scripts-running" + await lockService.acquire(lockKey, { + expire: 60 * 60, + }) + + try { + const scriptPaths = await this.getPendingMigrations(paths) + for (const script of scriptPaths) { + const scriptFn = await dynamicImport(script) + + if (!scriptFn.default) { + throw new Error( + `Failed to load migration script ${script}. No default export found.` + ) + } + + const scriptName = basename(script) + + const err = await this.insertMigration([ + { script_name: `'${scriptName}'` }, + ]).catch((e) => e) + + /** + * In case another processes is running in parallel, the migration might + * have already been executed and therefore the insert will fail because of the + * unique constraint. + */ + if (err) { + if (err.constraint === "idx_script_name_unique") { + continue + } + + throw err + } + + logger.info(`Running migration script ${script}`) + try { + const tracker = this.trackDuration() + + await scriptFn.default({ container: this.container }) + + logger.info( + `Migration script ${script} completed (${tracker.getSeconds()}s)` + ) + + await this.#updateMigrationFinishedAt(scriptName) + } catch (error) { + logger.error(`Failed to run migration script ${script}:`, error) + await this.#deleteMigration(scriptName) + throw error + } + } + } finally { + await lockService.release(lockKey) + } + } + + async getPendingMigrations(migrationPaths: string[]): Promise { + const executedMigrations = new Set( + (await this.getExecutedMigrations()).map((item) => item.script_name) + ) + const all = await this.loadMigrationFiles(migrationPaths) + + return all.filter((item) => !executedMigrations.has(basename(item))) + } + + protected async createMigrationTable(): Promise { + await this.pgConnection.raw(` + CREATE TABLE IF NOT EXISTS ${this.migration_table_name} ( + id SERIAL PRIMARY KEY, + script_name VARCHAR(255) NOT NULL, + created_at TIMESTAMP WITH TIME ZONE DEFAULT CURRENT_TIMESTAMP, + finished_at TIMESTAMP WITH TIME ZONE + ); + + CREATE UNIQUE INDEX IF NOT EXISTS idx_script_name_unique ON ${this.migration_table_name} (script_name); + `) + } + + #updateMigrationFinishedAt(scriptName: string) { + return this.pgConnection.raw( + `UPDATE ${this.migration_table_name} SET finished_at = CURRENT_TIMESTAMP WHERE script_name = ?`, + [scriptName] + ) + } + + #deleteMigration(scriptName: string) { + return this.pgConnection.raw( + `DELETE FROM ${this.migration_table_name} WHERE script_name = ?`, + [scriptName] + ) + } +} diff --git a/packages/core/types/src/common/batch.ts b/packages/core/types/src/common/batch.ts index 7109ffc92ac4f..bf563fe89e6b0 100644 --- a/packages/core/types/src/common/batch.ts +++ b/packages/core/types/src/common/batch.ts @@ -3,28 +3,75 @@ export type LinkMethodRequest = { remove?: string[] } +/** + * Links to manage for a data model. + * + * For example, to add or remove links between a collection and products, + * you pass in the `id` the collection's ID, in `add` the IDs of products + * to create links to the collection, and in `remove` the IDs of products + * to remove links from the collection. + */ export type LinkWorkflowInput = { + /** + * The ID of the data model to create links to or remove links from. + */ id: string + /** + * The IDs of the other data models to create links to the record specified in `id`. + */ add?: string[] + /** + * The IDs of the other data models to remove links from the record specified in `id`. + */ remove?: string[] } +/** + * Data to manage in bulk related to a model. + */ export type BatchMethodRequest = { + /** + * Records to create in bulk. + */ create?: TCreate[] + /** + * Records to update in bulk. + */ update?: TUpdate[] + /** + * Records to delete in bulk. + */ delete?: TDelete[] } +/** + * The result of a bulk operation related to a model. + */ export type BatchMethodResponse = { + /** + * The records that were created in the bulk operation. + */ created: T[] + /** + * The records that were updated in the bulk operation. + */ updated: T[] + /** + * The IDs of the records deleted in the bulk operation. + */ deleted: string[] } +/** + * Data to manage in bulk. + */ export type BatchWorkflowInput< TCreate, TUpdate, TDelete = string > = BatchMethodRequest +/** + * The data result of a bulk operation. + */ export type BatchWorkflowOutput = BatchMethodResponse diff --git a/packages/core/types/src/order/common.ts b/packages/core/types/src/order/common.ts index 655bb2a0c7d9e..a06d56e4259be 100644 --- a/packages/core/types/src/order/common.ts +++ b/packages/core/types/src/order/common.ts @@ -3034,13 +3034,28 @@ export interface OrderChangeReturn { shippingMethods: any[] } +/** + * The details of an order after a change is applied on it. + */ export interface OrderPreviewDTO extends Omit { + /** + * The details of the changes made on the order. + */ order_change: OrderChangeDTO + /** + * The items of the order, along with changes on the items. + */ items: (OrderLineItemDTO & { actions?: OrderChangeActionDTO[] })[] + /** + * The shipping methods of the order, along with changes on the shipping methods. + */ shipping_methods: (OrderShippingMethodDTO & { actions?: OrderChangeActionDTO[] })[] + /** + * The total amount for the requested return. + */ return_requested_total: number } diff --git a/packages/core/types/src/order/mutations.ts b/packages/core/types/src/order/mutations.ts index 7e9ef63d9c41e..0288d380f14a0 100644 --- a/packages/core/types/src/order/mutations.ts +++ b/packages/core/types/src/order/mutations.ts @@ -1974,8 +1974,18 @@ export interface UpdateOrderExchangeWithSelectorDTO { */ data: Partial } + +/** + * The details of the return cancelation. + */ export interface CancelOrderReturnDTO extends BaseOrderBundledActionsDTO { + /** + * The return's ID. + */ return_id: string + /** + * The ID of the user canceling the return. + */ canceled_by?: string } @@ -2062,8 +2072,17 @@ export interface CreateOrderClaimDTO extends BaseOrderBundledActionsDTO { created_by?: string | null } +/** + * The details of tjhe claim cancelation. + */ export interface CancelOrderClaimDTO extends BaseOrderBundledActionsDTO { + /** + * The claim's ID. + */ claim_id: string + /** + * The ID of the user canceling the claim + */ canceled_by?: string } @@ -2113,8 +2132,17 @@ export interface CreateOrderExchangeDTO extends BaseOrderBundledActionsDTO { created_by?: string | null } +/** + * The details of the exchange cancelation. + */ export interface CancelOrderExchangeDTO extends BaseOrderBundledActionsDTO { + /** + * The exchange's ID. + */ exchange_id: string + /** + * The ID of the user canceling the exchange + */ canceled_by?: string } diff --git a/packages/core/types/src/workflow/order/accept-transfer.ts b/packages/core/types/src/workflow/order/accept-transfer.ts index 1423c1a794a2b..52dc9a9663160 100644 --- a/packages/core/types/src/workflow/order/accept-transfer.ts +++ b/packages/core/types/src/workflow/order/accept-transfer.ts @@ -1,4 +1,13 @@ +/** + * The details of the order transfer request. + */ export interface AcceptOrderTransferWorkflowInput { + /** + * The ID of the order to accept the transfer for. + */ order_id: string + /** + * The token of the transfer request. + */ token: string } diff --git a/packages/core/types/src/workflow/order/begin-claim-order.ts b/packages/core/types/src/workflow/order/begin-claim-order.ts index 3246c6bb783ba..f08339e6bb9a7 100644 --- a/packages/core/types/src/workflow/order/begin-claim-order.ts +++ b/packages/core/types/src/workflow/order/begin-claim-order.ts @@ -1,13 +1,31 @@ import { OrderClaimType } from "../../order/mutations" +/** + * The details of the order claim to be requested. + */ export interface BeginOrderClaimWorkflowInput { + /** + * The type of the order claim. + */ type: OrderClaimType + /** + * The ID of the order to create the claim for. + */ order_id: string /** - * The id of the user that creates the order claim + * The ID of the user creating the order claim. */ created_by?: string | null + /** + * An internal note viewed by admin users only. + */ internal_note?: string + /** + * A description of the order claim. + */ description?: string + /** + * Custom key-value pairs of data to store in the order claim. + */ metadata?: Record | null } diff --git a/packages/core/types/src/workflow/order/begin-exchange-order.ts b/packages/core/types/src/workflow/order/begin-exchange-order.ts index d449a5153274f..2738f8a3d1ac8 100644 --- a/packages/core/types/src/workflow/order/begin-exchange-order.ts +++ b/packages/core/types/src/workflow/order/begin-exchange-order.ts @@ -1,10 +1,25 @@ +/** + * The details to request an order exchange. + */ export interface BeginOrderExchangeWorkflowInput { + /** + * The ID of the order to request an exchange for. + */ order_id: string /** * The id of the user that creates the order exchange */ created_by?: string | null + /** + * An internal note viewed only by admin users. + */ internal_note?: string + /** + * A description of the exchange. + */ description?: string + /** + * Custom key-value pairs of data to store in the exchange. + */ metadata?: Record | null } diff --git a/packages/core/types/src/workflow/order/begin-order-edit.ts b/packages/core/types/src/workflow/order/begin-order-edit.ts index 022515714298b..11cfa8c17f8b9 100644 --- a/packages/core/types/src/workflow/order/begin-order-edit.ts +++ b/packages/core/types/src/workflow/order/begin-order-edit.ts @@ -1,7 +1,25 @@ +/** + * The details of the order edit request. + */ export interface BeginorderEditWorkflowInput { + /** + * The ID of the order to request an edit for. + */ order_id: string + /** + * The ID of the user requesting the order edit. + */ created_by?: string + /** + * A note viewed by admins only related to the order edit. + */ internal_note?: string + /** + * Describes the reason for the order edit. + */ description?: string + /** + * Custom key-value pairs of data to store in the order edit. + */ metadata?: Record | null } diff --git a/packages/core/types/src/workflow/order/begin-return-order.ts b/packages/core/types/src/workflow/order/begin-return-order.ts index 918ab0497bd76..b000afd72ea6b 100644 --- a/packages/core/types/src/workflow/order/begin-return-order.ts +++ b/packages/core/types/src/workflow/order/begin-return-order.ts @@ -1,11 +1,29 @@ +/** + * The details of a return to create. + */ export interface BeginOrderReturnWorkflowInput { + /** + * The ID of the order to create the return for. + */ order_id: string + /** + * The ID of the location to return the items to. + */ location_id?: string /** - * The id of the user that creates the return + * The ID of the user creating the return. */ created_by?: string | null + /** + * A note viewed by admins only related to the return. + */ internal_note?: string + /** + * Description of the return. + */ description?: string + /** + * Custom key-value pairs of data to store in the return. + */ metadata?: Record | null } diff --git a/packages/core/types/src/workflow/order/cancel-claim.ts b/packages/core/types/src/workflow/order/cancel-claim.ts index 0ddf9d8d754c6..01131d3b28bbc 100644 --- a/packages/core/types/src/workflow/order/cancel-claim.ts +++ b/packages/core/types/src/workflow/order/cancel-claim.ts @@ -1,5 +1,17 @@ +/** + * The details of the order claim to be canceled. + */ export interface CancelOrderClaimWorkflowInput { + /** + * The ID of the claim to cancel. + */ claim_id: string + /** + * Whether to notify the customer of the cancellation. + */ no_notification?: boolean + /** + * The ID of the user canceling the claim. + */ canceled_by?: string } diff --git a/packages/core/types/src/workflow/order/cancel-exchange.ts b/packages/core/types/src/workflow/order/cancel-exchange.ts index 71f63a88825aa..20e83afd4db2d 100644 --- a/packages/core/types/src/workflow/order/cancel-exchange.ts +++ b/packages/core/types/src/workflow/order/cancel-exchange.ts @@ -1,5 +1,17 @@ +/** + * The details to cancel an order exchange. + */ export interface CancelOrderExchangeWorkflowInput { + /** + * The ID of the exchange to cancel. + */ exchange_id: string + /** + * Whether to notify the customer of the cancellation. + */ no_notification?: boolean + /** + * The ID of the user that's canceling the exchange. + */ canceled_by?: string } diff --git a/packages/core/types/src/workflow/order/cancel-order.ts b/packages/core/types/src/workflow/order/cancel-order.ts index 04f28a4d25505..a5c48f6d9093d 100644 --- a/packages/core/types/src/workflow/order/cancel-order.ts +++ b/packages/core/types/src/workflow/order/cancel-order.ts @@ -1,5 +1,17 @@ +/** + * The details of the order cancelation. + */ export interface CancelOrderWorkflowInput { + /** + * The ID of the order to cancel. + */ order_id: string + /** + * Whether to notify the customer of the cancelation. + */ no_notification?: boolean + /** + * The ID of the user that canceled the order. + */ canceled_by?: string } diff --git a/packages/core/types/src/workflow/order/cancel-return.ts b/packages/core/types/src/workflow/order/cancel-return.ts index dac126a613f1d..b8b8d6073e918 100644 --- a/packages/core/types/src/workflow/order/cancel-return.ts +++ b/packages/core/types/src/workflow/order/cancel-return.ts @@ -1,5 +1,17 @@ +/** + * The details to cancel a return. + */ export interface CancelReturnWorkflowInput { + /** + * The ID of the return to cancel. + */ return_id: string + /** + * Whether to notify the customer of the return cancellation. + */ no_notification?: boolean + /** + * The ID of the user that's canceling the return. + */ canceled_by?: string } diff --git a/packages/core/types/src/workflow/order/cancel-transfer.ts b/packages/core/types/src/workflow/order/cancel-transfer.ts index 9d0bcba83c84b..7e6f274c1a42e 100644 --- a/packages/core/types/src/workflow/order/cancel-transfer.ts +++ b/packages/core/types/src/workflow/order/cancel-transfer.ts @@ -1,5 +1,17 @@ +/** + * The details of the order transfer cancelation. + */ export type CancelTransferOrderRequestWorkflowInput = { + /** + * The ID of the order to cancel the transfer for. + */ order_id: string + /** + * The ID of the authenticated user requesting to cancel the transfer. + */ logged_in_user_id: string + /** + * The actor type requesting to cancel the transfer. + */ actor_type: "customer" | "user" } diff --git a/packages/core/types/src/workflow/order/create-return-order.ts b/packages/core/types/src/workflow/order/create-return-order.ts index 6d374e710ba84..c6d4b24e6cd50 100644 --- a/packages/core/types/src/workflow/order/create-return-order.ts +++ b/packages/core/types/src/workflow/order/create-return-order.ts @@ -1,29 +1,86 @@ import { BigNumberInput } from "../../totals" import { CreateFulfillmentLabelWorkflowDTO } from "../fulfillment/create-fulfillment" +/** + * The details of an item to be returned. + */ export interface CreateReturnItem { + /** + * The ID of the order item to return. + */ id: string + /** + * The quantity of the item to return. + */ quantity: BigNumberInput + /** + * An internal note viewed only by admin users. + */ internal_note?: string | null + /** + * The ID of the reason indicating why the item is being returned. + */ reason_id?: string | null + /** + * More details about the returned item. + */ note?: string | null + /** + * Custom key-value pairs of data to store in the return item. + */ metadata?: Record | null } +/** + * The details to create a return order. + */ export interface CreateOrderReturnWorkflowInput { + /** + * The ID of the order to return items from. + */ order_id: string - created_by?: string | null // The id of the authenticated user + /** + * The ID of the customer that's creating the return + */ + created_by?: string | null + /** + * The items to return. + */ items: CreateReturnItem[] + /** + * The shipping details of the returned items. + */ return_shipping?: { + /** + * The ID of the shipping option to use for the return. + */ option_id: string + /** + * The custom amount to create the return shipping with. + * If not provided, the shipping option's amount is used. + */ price?: number + /** + * The shipmen's label details. + */ labels?: CreateFulfillmentLabelWorkflowDTO[] } + /** + * More details about the return. + */ note?: string | null + /** + * Whether to mark the return as received immediately. + */ receive_now?: boolean + /** + * The amount to refund the customer. + */ refund_amount?: number /** - * Default fallback to the shipping option location id + * The ID of the location to return the items to. + * If not provided, the return shipping option's location + * is used. */ location_id?: string | null } diff --git a/packages/core/types/src/workflow/order/decline-transfer.ts b/packages/core/types/src/workflow/order/decline-transfer.ts index d727eb891e1ab..b8ad518d9f0fe 100644 --- a/packages/core/types/src/workflow/order/decline-transfer.ts +++ b/packages/core/types/src/workflow/order/decline-transfer.ts @@ -1,4 +1,13 @@ +/** + * The details of declining a transfer order request. + */ export type DeclineTransferOrderRequestWorkflowInput = { + /** + * The ID of the order to decline the transfer for. + */ order_id: string + /** + * The token of the order transfer request. + */ token: string } diff --git a/packages/core/types/src/workflow/order/items.ts b/packages/core/types/src/workflow/order/items.ts index a069d15196ee9..9d599509aa0d5 100644 --- a/packages/core/types/src/workflow/order/items.ts +++ b/packages/core/types/src/workflow/order/items.ts @@ -1,90 +1,232 @@ import { ClaimReason } from "../../order/mutations" import { BigNumberInput } from "../../totals" +/** + * The details of a line item to add to an order. + */ interface NewItem { + /** + * The ID of the variant to add to the order. + */ variant_id: string + /** + * The quantity of the item to add to the order. + */ quantity: BigNumberInput + /** + * The price of a single quantity of the item. + */ unit_price?: BigNumberInput | null + /** + * The original price of the item before a promotion or sale. + */ compare_at_unit_price?: BigNumberInput | null + /** + * A note viewed by admins only related to the item. + */ internal_note?: string | null + /** + * Custom key-value pairs to store additional information about the item. + */ metadata?: Record | null } +/** + * The details of an existing item in an order. + */ interface ExistingItem { + /** + * The ID of the order item. + */ id: string + /** + * The item's quantity. + */ quantity: BigNumberInput + /** + * The price of a single quantity of the item. + */ unit_price?: BigNumberInput | null + /** + * The original price of the item before a promotion or sale. + */ compare_at_unit_price?: BigNumberInput | null + /** + * A note viewed by admins only related to the item. + */ internal_note?: string | null } +/** + * The details of the outbound or new items to add to an exchange. + */ export interface OrderExchangeAddNewItemWorkflowInput { + /** + * The ID of the exchange to add the items to. + */ exchange_id: string + /** + * The items to add to the exchange. + */ items: NewItem[] } +/** + * The details of the outbound or new items to add to a claim. + */ export interface OrderClaimAddNewItemWorkflowInput { + /** + * The ID of the claim to add the items to. + */ claim_id: string + /** + * The items to add to the claim. + */ items: NewItem[] } -export interface OrderExchangeAddNewItemWorkflowInput { - exchange_id: string - items: NewItem[] -} - +/** + * The details of the items to add to an order edit. + */ export interface OrderEditAddNewItemWorkflowInput { + /** + * The ID of the order to add the items to its edit. + */ order_id: string + /** + * The items to add to the order's edit. + */ items: NewItem[] } +/** + * The details of updating an order items' quantity in the order's edit. + */ export interface OrderEditUpdateItemQuantityWorkflowInput { + /** + * The ID of the order to update the items in its edit. + */ order_id: string + /** + * The order items to update their quantity in the order's edit. + */ items: ExistingItem[] } +/** + * The details of the line items to add to the order. + */ export interface OrderAddLineItemWorkflowInput { + /** + * The ID of the order to add the line items to. + */ order_id: string + /** + * The items to add to the order. + */ items: NewItem[] } +/** + * The details of the outbound or new item to update in an order. + */ export interface UpdateExchangeAddNewItemWorkflowInput { + /** + * The ID of the exchange to update the item in. + */ exchange_id: string + /** + * The ID of the action associated with the item to update. + * Every item has an `actions` property, whose value is an array of actions. + * You can find the action with the name `ITEM_ADD` using the item's `action` property, + * and use the value of the action's `id` property. + */ action_id: string + /** + * The data to update in the item. + */ data: { + /** + * The new quantity of the item. + */ quantity?: BigNumberInput + /** + * A note viewed by admins only related to the item. + */ internal_note?: string | null } } +/** + * The details of the item to update in an order edit. + */ export interface UpdateOrderEditAddNewItemWorkflowInput { + /** + * The ID of the order to update the item in its edit. + */ order_id: string + /** + * The ID of the action associated with the item to update. + * Every item has an `actions` property, whose value is an array of actions. + * You can find the action with the name `ITEM_ADD` using the item's `action` property, + * and use the value of the action's `id` property. + */ action_id: string + /** + * The details to update in the item. + */ data: { + /** + * The new quantity of the item. + */ quantity?: BigNumberInput + /** + * The price of a single quantity of the item. + */ unit_price?: BigNumberInput | null + /** + * The original price of the item before a promotion or sale. + */ compare_at_unit_price?: BigNumberInput | null + /** + * A note viewed by admins only related to the item. + */ internal_note?: string | null } } +/** + * The details to update an existing order item that was added previously to an order edit. + */ export interface UpdateOrderEditItemQuantityWorkflowInput extends UpdateOrderEditAddNewItemWorkflowInput {} +/** + * The details to update a claim's outbound item. + */ export interface UpdateClaimAddNewItemWorkflowInput { + /** + * The ID of the claim to update the outbound item in. + */ claim_id: string + /** + * The ID of the action associated with the item to update. + * Every item has an `actions` property, whose value is an array of actions. + * You can find the action with the name `ITEM_ADD` using the item's `action` property, + * and use the value of the action's `id` property. + */ action_id: string + /** + * The details to update in the outbound item. + */ data: { + /** + * The new quantity of the item. + */ quantity?: BigNumberInput - internal_note?: string | null - } -} - -export interface UpdateExchangeAddNewItemWorkflowInput { - exchange_id: string - action_id: string - data: { - quantity?: BigNumberInput + /** + * A note viewed by admins only related to the item. + */ internal_note?: string | null } } @@ -103,13 +245,39 @@ export interface UpdateExchangeAddItemWorkflowInput { } } +/** + * The details of the order items to add to a claim. + */ export interface OrderClaimItemWorkflowInput { + /** + * The ID of the claim to add the items to. + */ claim_id: string - items: (ExistingItem & { reason?: ClaimReason })[] + /** + * The items to add to the claim. + */ + items: (ExistingItem & { + /** + * The reason for adding the item to the claim. + */ + reason?: ClaimReason + })[] } +/** + * The details of the item to update in a claim. + */ export interface UpdateClaimItemWorkflowInput { + /** + * The ID of the claim to update the item in. + */ claim_id: string + /** + * The ID of the action associated with the item to update. + * Every item has an `actions` property, whose value is an array of actions. + * You can find the action with the name `WRITE_OFF_ITEM` using its `action` property, + * and use the value of its `id` property. + */ action_id: string data: { quantity?: BigNumberInput @@ -118,17 +286,50 @@ export interface UpdateClaimItemWorkflowInput { } } +/** + * The details of the outbound item to remove from an exchange. + */ export interface DeleteOrderExchangeItemActionWorkflowInput { + /** + * The ID of the exchange to remove the item from. + */ exchange_id: string + /** + * The ID of the action associated with the item to remove. + * Every item has an `actions` property, whose value is an array of actions. + * You can find the action with the name `ITEM_ADD` using the item's `action` property, + * and use the value of the action's `id` property. + */ action_id: string } +/** + * The details of the item to remove from a claim. + */ export interface DeleteOrderClaimItemActionWorkflowInput { + /** + * The ID of the claim to remove the item from. + */ claim_id: string + /** + * The ID of the action associated with the item to remove. + */ action_id: string } +/** + * The details to remove an item previously added to an order edit. + */ export interface DeleteOrderEditItemActionWorkflowInput { + /** + * The ID of the order to remove the item from its edit. + */ order_id: string + /** + * The ID of the action associated with the item to remove. + * Every item has an `actions` property, whose value is an array of actions. + * You can find the action with the name `ITEM_ADD` using the item's `action` property, + * and use the value of the action's `id` property. + */ action_id: string } diff --git a/packages/core/types/src/workflow/order/receive-return.ts b/packages/core/types/src/workflow/order/receive-return.ts index 8a3683ec09726..3a9afed9fbab8 100644 --- a/packages/core/types/src/workflow/order/receive-return.ts +++ b/packages/core/types/src/workflow/order/receive-return.ts @@ -1,39 +1,123 @@ import { BigNumberInput } from "../../totals" +/** + * The details of an item to be received in a return. + */ interface ReceiveReturnItem { + /** + * The ID of the order item to receive. + */ id: string + /** + * The quantity of the item to receive. + */ quantity: BigNumberInput + /** + * An internal note viewed only by admin users. + */ internal_note?: string + /** + * Custom key-value pairs of data to store in the return item. + */ metadata?: Record | null } +/** + * The details of a return requested to be received. + */ export interface BeginReceiveOrderReturnWorkflowInput { + /** + * The ID of the return to receive. + */ return_id: string - created_by?: string // The id of the authenticated user + /** + * The ID of the user that's requesting the return receival. + */ + created_by?: string + /** + * Description of the return receival. + */ description?: string + /** + * A note viewed by admins only related to the return receival. + */ internal_note?: string + /** + * Custom key-value pairs of data to store in the return receival. + */ metadata?: Record | null } +/** + * The data to mark items as received in a return. + */ export interface ReceiveOrderReturnItemsWorkflowInput { + /** + * The ID of the return to mark its items as received. + */ return_id: string + /** + * The items to mark as received. + */ items: ReceiveReturnItem[] } +/** + * The data to mark a return as received and completed. + */ export interface ReceiveCompleteOrderReturnWorkflowInput { + /** + * The ID of the return to receive and complete. + */ return_id: string - created_by?: string // The id of the authenticated user + /** + * The ID of the user that's receiving and completing the return. + */ + created_by?: string + /** + * The received items. + */ items: ReceiveReturnItem[] + /** + * Description of the return receival. + */ description?: string + /** + * A note viewed by admins only related to the return receival. + */ internal_note?: string + /** + * Custom key-value pairs of data to store in the return receival. + */ metadata?: Record | null } +/** + * The details of updating an item in a return receival request. + */ export interface UpdateReceiveItemReturnRequestWorkflowInput { + /** + * The ID of the return to update the item in. + */ return_id: string + /** + * The ID of the action associated with the item to update. + * Every return item has an `actions` property, whose value is an array of actions. + * You can find the action with the name `RECEIVE_RETURN_ITEM` using its `action` property, and use the value of + * its `id` property. + */ action_id: string + /** + * The data to update in the item. + */ data: { + /** + * The new quantity of the item. + */ quantity?: BigNumberInput + /** + * An internal note viewed only by admin users. + */ internal_note?: string | null } } diff --git a/packages/core/types/src/workflow/order/request-item-return.ts b/packages/core/types/src/workflow/order/request-item-return.ts index 90dd9791a0691..256466937ba69 100644 --- a/packages/core/types/src/workflow/order/request-item-return.ts +++ b/packages/core/types/src/workflow/order/request-item-return.ts @@ -1,28 +1,85 @@ import { BigNumberInput } from "../../totals" import { CreateReturnItem } from "./create-return-order" +/** + * The details of adding items to a return. + */ export interface RequestItemReturnWorkflowInput { + /** + * The ID of the return to add the items to. + */ return_id: string + /** + * The ID of the claim associated with the return, if any. + */ claim_id?: string + /** + * The ID of the exchange associated with the return, if any. + */ exchange_id?: string + /** + * The items to add to the return. + */ items: CreateReturnItem[] } +/** + * The details of updating a requested item in a return. + */ export interface UpdateRequestItemReturnWorkflowInput { + /** + * The ID of the return to update the item in. + */ return_id: string + /** + * The ID of the claim associated with the return, if any. + */ claim_id?: string + /** + * The ID of the exchange associated with the return, if any. + */ exchange_id?: string + /** + * The ID of the action associated with the item to update. + * Every item has an `actions` property, whose value is an array of actions. + * You can find an action with the name `RETURN_ITEM` using its `action` property, + * and use the value of its `id` property. + */ action_id: string + /** + * The data to update in the item. + */ data: { + /** + * The new quantity of the item. + */ quantity?: BigNumberInput + /** + * An internal note viewed only by admin users. + */ internal_note?: string | null + /** + * The ID of the reason indicating why the item is being returned. + */ reason_id?: string | null } } +/** + * The details to return an item as part of an exchange. + */ export interface OrderExchangeRequestItemReturnWorkflowInput { + /** + * The ID of the return that's associated with the exchange. + */ return_id: string + /** + * The ID of the exchange to add the inbound items to. + */ exchange_id: string + /** + * The items to return as part of the exchange. + */ items: CreateReturnItem[] } export interface DeleteOrderExchangeRequestItemReturnWorkflowInput { @@ -30,17 +87,50 @@ export interface DeleteOrderExchangeRequestItemReturnWorkflowInput { action_id: string } +/** + * The details of the items to be returned as part of the claim. + */ export interface OrderClaimRequestItemReturnWorkflowInput { + /** + * The ID of the return that's associated with the claim. + */ return_id: string + /** + * The ID of the claim to add the items to. + */ claim_id: string + /** + * The items to add to the claim as inbound items. + */ items: CreateReturnItem[] } +/** + * The details of the item to be removed from the return. + */ export interface DeleteRequestItemReturnWorkflowInput { + /** + * The ID of the return to remove the item from. + */ return_id: string + /** + * The ID of the action associated with the item to remove. + * Every item has an `actions` property, whose value is an array of actions. + * You can find an action with the name `RETURN_ITEM` using its `action` property, + * and use the value of its `id` property. + */ action_id: string } +/** + * The details of the received item to be removed. + * + * @property return_id - The ID of the return to remove the item from. + * @property action_id - The ID of the action associated with the item to remove. + * Every item has an `actions` property, whose value is an array of actions. + * You can find an action with the name `RECEIVE_RETURN_ITEM` using its `action` property, + * and use the value of its `id` property. + */ export interface DeleteRequestItemReceiveReturnWorkflowInput extends DeleteRequestItemReturnWorkflowInput {} diff --git a/packages/core/types/src/workflow/order/shipping-method.ts b/packages/core/types/src/workflow/order/shipping-method.ts index dc0c75d0f06fc..44bf10a51452b 100644 --- a/packages/core/types/src/workflow/order/shipping-method.ts +++ b/packages/core/types/src/workflow/order/shipping-method.ts @@ -1,61 +1,205 @@ import { BigNumberInput } from "../../totals" +/** + * The details to update a shipping method of a return. + */ export interface UpdateReturnShippingMethodWorkflowInput { + /** + * The ID of the return to update its shipping method. + */ return_id: string + /** + * The ID of the action associated with the shipping method to update. + * Every shipping method has an `actions` property, whose value is an array of actions. + * You can find the action with the name `SHIPPING_ADD` using its `action` property, and use the value of + * its `id` property. + */ action_id: string + /** + * The data to update in the shipping method. + */ data: { + /** + * Set a custom amount for the shipping method. + */ custom_amount?: BigNumberInput | null + /** + * A note viewed by admins only related to the shipping method. + */ internal_note?: string | null + /** + * Custom key-value pairs of data to store in the shipping method. + */ metadata?: Record | null } } +/** + * The details to delete a shipping method from a return. + */ export interface DeleteReturnShippingMethodWorkflowInput { + /** + * The ID of the return to delete the shipping method from. + */ return_id: string + /** + * The ID of the action associated with the shipping method to remove. + * Every shipping method has an `actions` property, whose value is an array of actions. + * You can find the action with the name `SHIPPING_ADD` using its `action` property, and use the value of + * its `id` property. + */ action_id: string } +/** + * The details of the shipping method to be updated on the claim. + */ export interface UpdateClaimShippingMethodWorkflowInput { + /** + * The ID of the claim to update the shipping method on. + */ claim_id: string + /** + * The ID of the action associated with the shipping method to update. + * Every shipping method has an `actions` property, whose value is an array of actions. + * You can find the action with the name `SHIPPING_ADD` using its `action` property, and use the value of + * its `id` property. + */ action_id: string + /** + * The data to update in the shipping method. + */ data: { + /** + * Set a custom amount for the shipping method. + */ custom_amount?: BigNumberInput | null + /** + * A note viewed by admins only related to the shipping method. + */ internal_note?: string | null + /** + * Custom key-value pairs of data to store in the shipping method. + */ metadata?: Record | null } } +/** + * The details of the shipping method to be deleted from the claim. + */ export interface DeleteClaimShippingMethodWorkflowInput { + /** + * The ID of the claim to delete the shipping method from. + */ claim_id: string + /** + * The ID of the action associated with the shipping method to remove. + * Every shipping method has an `actions` property, whose value is an array of actions. + * You can find the action with the name `SHIPPING_ADD` using its `action` property, and use the value of + * its `id` property. + */ action_id: string } +/** + * The details of the shipping method to be updated in the exchange. + */ export interface UpdateExchangeShippingMethodWorkflowInput { + /** + * The ID of the exchange to update the shipping method in. + */ exchange_id: string + /** + * The ID of the action associated with the shipping method to update. + * Every shipping method has an `actions` property, whose value is an array of actions. + * You can find the action with the name `SHIPPING_ADD` using its `action` property, and use the value of + * its `id` property. + */ action_id: string + /** + * The data to update in the shipping method. + */ data: { + /** + * Set a custom amount for the shipping method. + */ custom_amount?: BigNumberInput | null + /** + * A note viewed by admins only related to the shipping method. + */ internal_note?: string | null + /** + * Custom key-value pairs of data to store in the shipping method. + */ metadata?: Record | null } } +/** + * The details of the shipping method to be updated in the order edit. + */ export interface UpdateOrderEditShippingMethodWorkflowInput { + /** + * The ID of the order to update the shipping method in its edit. + */ order_id: string + /** + * The ID of the action associated with the shipping method to update. + * Every shipping method has an `actions` property, whose value is an array of actions. + * You can find the action with the name `SHIPPING_ADD` using its `action` property, and use the value of + * its `id` property. + */ action_id: string + /** + * The details to update in the shipping method. + */ data: { + /** + * Set a custom amount for the shipping method. + */ custom_amount?: BigNumberInput | null + /** + * A note viewed by admins only related to the shipping method. + */ internal_note?: string | null + /** + * Custom key-value pairs of data to store in the shipping method. + */ metadata?: Record | null } } +/** + * The details of the shipping method to be deleted from the exchange. + */ export interface DeleteExchangeShippingMethodWorkflowInput { + /** + * The ID of the exchange to delete the shipping method from. + */ exchange_id: string + /** + * The ID of the action associated with the shipping method to remove. + * Every shipping method has an `actions` property, whose value is an array of actions. + * You can find the action with the name `SHIPPING_ADD` using its `action` property, and use the value of + * its `id` property. + */ action_id: string } +/** + * The details to delete a shipping method from an order edit. + */ export interface DeleteOrderEditShippingMethodWorkflowInput { + /** + * The ID of the order to delete the shipping method from. + */ order_id: string + /** + * The ID of the action associated with the shipping method to remove. + * Every shipping method has an `actions` property, whose value is an array of actions. + * You can find the action with the name `SHIPPING_ADD` using its `action` property, and use the value of + * its `id` property. + */ action_id: string } diff --git a/packages/core/types/src/workflow/order/update-order.ts b/packages/core/types/src/workflow/order/update-order.ts index e9c0b0357f96d..bcc0f3ea429e1 100644 --- a/packages/core/types/src/workflow/order/update-order.ts +++ b/packages/core/types/src/workflow/order/update-order.ts @@ -1,10 +1,30 @@ import { UpsertOrderAddressDTO } from "../../order" +/** + * The data to update an order's details. + */ export type UpdateOrderWorkflowInput = { + /** + * The ID of the order to update. + */ id: string + /** + * The ID of the user updating the order. + */ user_id: string + /** + * Create or update the shipping address of the order. + * Changing the country code will throw an error. + */ shipping_address?: UpsertOrderAddressDTO + /** + * Create or update the billing address of the order. + * Changing the country code will throw an error. + */ billing_address?: UpsertOrderAddressDTO + /** + * The new email of the order. + */ email?: string } diff --git a/packages/core/types/src/workflow/order/update-return.ts b/packages/core/types/src/workflow/order/update-return.ts index f348cf4d711ac..2f9524a9ca6e9 100644 --- a/packages/core/types/src/workflow/order/update-return.ts +++ b/packages/core/types/src/workflow/order/update-return.ts @@ -1,6 +1,21 @@ +/** + * The data to update a return's details. + */ export interface UpdateReturnWorkflowInput { + /** + * The ID of the return to update. + */ return_id: string + /** + * The ID of the stock location that items are returned to. + */ location_id?: string | null + /** + * Whether to notify the customer about the return update. + */ no_notification?: boolean + /** + * Custom key-value pairs of data to store in the return. + */ metadata?: Record | null } diff --git a/packages/core/types/src/workflow/product-category/index.ts b/packages/core/types/src/workflow/product-category/index.ts index 47236fd7154f7..6cfc22df5fad3 100644 --- a/packages/core/types/src/workflow/product-category/index.ts +++ b/packages/core/types/src/workflow/product-category/index.ts @@ -13,5 +13,8 @@ export interface UpdateProductCategoriesWorkflowInput { update: UpdateProductCategoryDTO } +/** + * The products to manage of a category. + */ export interface BatchUpdateProductsOnCategoryWorkflowInput extends LinkWorkflowInput {} diff --git a/packages/core/types/src/workflow/product/export-products.ts b/packages/core/types/src/workflow/product/export-products.ts index 85e6ae3afc3c0..aff88fc6cd768 100644 --- a/packages/core/types/src/workflow/product/export-products.ts +++ b/packages/core/types/src/workflow/product/export-products.ts @@ -1,6 +1,17 @@ import { FilterableProductProps } from "../../product" +/** + * The configurations to export products. + */ export interface ExportProductsDTO { + /** + * The fields to select. These fields will be passed to + * [Query](https://docs.medusajs.com/learn/fundamentals/module-links/query), so you can + * pass product properties or any relation names, including custom links. + */ select: string[] + /** + * The filters to select which products to export. + */ filter?: FilterableProductProps } diff --git a/packages/core/types/src/workflow/product/import-products.ts b/packages/core/types/src/workflow/product/import-products.ts index 14de827620d5f..1fa0b04a8f019 100644 --- a/packages/core/types/src/workflow/product/import-products.ts +++ b/packages/core/types/src/workflow/product/import-products.ts @@ -1,5 +1,14 @@ +/** + * The configurations to import products. + */ export interface ImportProductsDTO { + /** + * The content of the CSV file. + */ fileContent: string + /** + * The name of the CSV file. + */ filename: string } diff --git a/packages/core/utils/src/product/get-variant-availability.ts b/packages/core/utils/src/product/get-variant-availability.ts index 1d47ffec9af89..aba2b170f85fa 100644 --- a/packages/core/utils/src/product/get-variant-availability.ts +++ b/packages/core/utils/src/product/get-variant-availability.ts @@ -1,5 +1,22 @@ import { RemoteQueryFunction } from "@medusajs/types" +/** + * The computed inventory availability for variants in a given sales channel. + * The object's keys are the variant IDs. + */ +export type VariantAvailabilityResult = { + [variant_id: string]: { + /** + * The available inventory quantity for the variant in the sales channel. + */ + availability: number + /** + * The ID of the sales channel for which the availability was computed. + */ + sales_channel_id: string + } +} + /** * Computes the varaint availability for a list of variants in a given sales channel * @@ -23,12 +40,7 @@ import { RemoteQueryFunction } from "@medusajs/types" export async function getVariantAvailability( query: Omit, data: VariantAvailabilityData -): Promise<{ - [variant_id: string]: { - availability: number - sales_channel_id: string - } -}> { +): Promise { const { variantInventoriesMap, locationIds } = await getDataForComputation( query, data diff --git a/packages/design-system/icons/src/components/__tests__/house-star.spec.tsx b/packages/design-system/icons/src/components/__tests__/house-star.spec.tsx new file mode 100644 index 0000000000000..79114305d868c --- /dev/null +++ b/packages/design-system/icons/src/components/__tests__/house-star.spec.tsx @@ -0,0 +1,17 @@ + import * as React from "react" + import { cleanup, render, screen } from "@testing-library/react" + + import HouseStar from "../house-star" + + describe("HouseStar", () => { + it("should render the icon without errors", async () => { + render() + + + const svgElement = screen.getByTestId("icon") + + expect(svgElement).toBeInTheDocument() + + cleanup() + }) + }) \ No newline at end of file diff --git a/packages/design-system/icons/src/components/__tests__/shield-check.spec.tsx b/packages/design-system/icons/src/components/__tests__/shield-check.spec.tsx new file mode 100644 index 0000000000000..defb50cfd9dc4 --- /dev/null +++ b/packages/design-system/icons/src/components/__tests__/shield-check.spec.tsx @@ -0,0 +1,17 @@ + import * as React from "react" + import { cleanup, render, screen } from "@testing-library/react" + + import ShieldCheck from "../shield-check" + + describe("ShieldCheck", () => { + it("should render the icon without errors", async () => { + render() + + + const svgElement = screen.getByTestId("icon") + + expect(svgElement).toBeInTheDocument() + + cleanup() + }) + }) \ No newline at end of file diff --git a/packages/design-system/icons/src/components/__tests__/tag-illustration.spec.tsx b/packages/design-system/icons/src/components/__tests__/tag-illustration.spec.tsx new file mode 100644 index 0000000000000..842b222e1683f --- /dev/null +++ b/packages/design-system/icons/src/components/__tests__/tag-illustration.spec.tsx @@ -0,0 +1,17 @@ + import * as React from "react" + import { cleanup, render, screen } from "@testing-library/react" + + import TagIllustration from "../tag-illustration" + + describe("TagIllustration", () => { + it("should render the icon without errors", async () => { + render() + + + const svgElement = screen.getByTestId("icon") + + expect(svgElement).toBeInTheDocument() + + cleanup() + }) + }) \ No newline at end of file diff --git a/packages/design-system/icons/src/components/house-star.tsx b/packages/design-system/icons/src/components/house-star.tsx new file mode 100644 index 0000000000000..97c8b81ac9d49 --- /dev/null +++ b/packages/design-system/icons/src/components/house-star.tsx @@ -0,0 +1,33 @@ +import * as React from "react" +import type { IconProps } from "../types" +const HouseStar = React.forwardRef( + ({ color = "currentColor", ...props }, ref) => { + return ( + + + + + ) + } +) +HouseStar.displayName = "HouseStar" +export default HouseStar diff --git a/packages/design-system/icons/src/components/index.ts b/packages/design-system/icons/src/components/index.ts index a56759909dce4..33c5637ada1ee 100644 --- a/packages/design-system/icons/src/components/index.ts +++ b/packages/design-system/icons/src/components/index.ts @@ -177,6 +177,7 @@ export { default as Hashtag } from "./hashtag" export { default as HeartBroken } from "./heart-broken" export { default as Heart } from "./heart" export { default as History } from "./history" +export { default as HouseStar } from "./house-star" export { default as House } from "./house" export { default as InboxSolid } from "./inbox-solid" export { default as InformationCircleSolid } from "./information-circle-solid" @@ -253,6 +254,7 @@ export { default as ServerStackSolid } from "./server-stack-solid" export { default as ServerStack } from "./server-stack" export { default as Server } from "./server" export { default as Share } from "./share" +export { default as ShieldCheck } from "./shield-check" export { default as Shipbob } from "./shipbob" export { default as ShoppingBag } from "./shopping-bag" export { default as ShoppingCartSolid } from "./shopping-cart-solid" @@ -287,6 +289,7 @@ export { default as SunSolid } from "./sun-solid" export { default as Sun } from "./sun" export { default as SwatchSolid } from "./swatch-solid" export { default as Swatch } from "./swatch" +export { default as TagIllustration } from "./tag-illustration" export { default as TagSolid } from "./tag-solid" export { default as Tag } from "./tag" export { default as Tailwind } from "./tailwind" diff --git a/packages/design-system/icons/src/components/shield-check.tsx b/packages/design-system/icons/src/components/shield-check.tsx new file mode 100644 index 0000000000000..123f753f599c6 --- /dev/null +++ b/packages/design-system/icons/src/components/shield-check.tsx @@ -0,0 +1,23 @@ +import * as React from "react" +import type { IconProps } from "../types" +const ShieldCheck = React.forwardRef( + ({ color = "currentColor", ...props }, ref) => { + return ( + + + + ) + } +) +ShieldCheck.displayName = "ShieldCheck" +export default ShieldCheck diff --git a/packages/design-system/icons/src/components/square-blue-solid.tsx b/packages/design-system/icons/src/components/square-blue-solid.tsx index 76698731f32b3..d03e862473015 100644 --- a/packages/design-system/icons/src/components/square-blue-solid.tsx +++ b/packages/design-system/icons/src/components/square-blue-solid.tsx @@ -13,13 +13,14 @@ const SquareBlueSolid = React.forwardRef( > ) diff --git a/packages/design-system/icons/src/components/square-green-solid.tsx b/packages/design-system/icons/src/components/square-green-solid.tsx index 43ac6e4dc5787..2dd1884067f16 100644 --- a/packages/design-system/icons/src/components/square-green-solid.tsx +++ b/packages/design-system/icons/src/components/square-green-solid.tsx @@ -13,13 +13,14 @@ const SquareGreenSolid = React.forwardRef( > ) diff --git a/packages/design-system/icons/src/components/square-grey-solid.tsx b/packages/design-system/icons/src/components/square-grey-solid.tsx index 44d73db761942..57447ddb2c8c9 100644 --- a/packages/design-system/icons/src/components/square-grey-solid.tsx +++ b/packages/design-system/icons/src/components/square-grey-solid.tsx @@ -13,13 +13,14 @@ const SquareGreySolid = React.forwardRef( > ) diff --git a/packages/design-system/icons/src/components/square-orange-solid.tsx b/packages/design-system/icons/src/components/square-orange-solid.tsx index f2cec51cdcdf3..65dbc7360d3d3 100644 --- a/packages/design-system/icons/src/components/square-orange-solid.tsx +++ b/packages/design-system/icons/src/components/square-orange-solid.tsx @@ -13,13 +13,14 @@ const SquareOrangeSolid = React.forwardRef( > ) diff --git a/packages/design-system/icons/src/components/square-purple-solid.tsx b/packages/design-system/icons/src/components/square-purple-solid.tsx index 8bc3bc4aa37f6..8ded5ff77af6c 100644 --- a/packages/design-system/icons/src/components/square-purple-solid.tsx +++ b/packages/design-system/icons/src/components/square-purple-solid.tsx @@ -13,13 +13,14 @@ const SquarePurpleSolid = React.forwardRef( > ) diff --git a/packages/design-system/icons/src/components/square-red-solid.tsx b/packages/design-system/icons/src/components/square-red-solid.tsx index df33a4c63ff03..9bdf2bd233f22 100644 --- a/packages/design-system/icons/src/components/square-red-solid.tsx +++ b/packages/design-system/icons/src/components/square-red-solid.tsx @@ -13,13 +13,14 @@ const SquareRedSolid = React.forwardRef( > ) diff --git a/packages/design-system/icons/src/components/tag-illustration.tsx b/packages/design-system/icons/src/components/tag-illustration.tsx new file mode 100644 index 0000000000000..73e97da437500 --- /dev/null +++ b/packages/design-system/icons/src/components/tag-illustration.tsx @@ -0,0 +1,133 @@ +import * as React from "react" +import type { IconProps } from "../types" +const TagIllustration = React.forwardRef( + ({ color = "currentColor", ...props }, ref) => { + return ( + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + ) + } +) +TagIllustration.displayName = "TagIllustration" +export default TagIllustration diff --git a/packages/medusa/src/api/store/customers/query-config.ts b/packages/medusa/src/api/store/customers/query-config.ts index 91d0e1a04ee74..2bd1eb234dfd3 100644 --- a/packages/medusa/src/api/store/customers/query-config.ts +++ b/packages/medusa/src/api/store/customers/query-config.ts @@ -36,6 +36,8 @@ export const defaultStoreCustomerAddressFields = [ "country_code", "phone", "metadata", + "is_default_shipping", + "is_default_billing", "created_at", "updated_at", ] diff --git a/packages/medusa/src/commands/db/migrate.ts b/packages/medusa/src/commands/db/migrate.ts index ad0a897e0bf63..1828115ecd4ef 100644 --- a/packages/medusa/src/commands/db/migrate.ts +++ b/packages/medusa/src/commands/db/migrate.ts @@ -11,6 +11,7 @@ import { syncLinks } from "./sync-links" import { ensureDbExists } from "../utils" import { initializeContainer } from "../../loaders" import { getResolvedPlugins } from "../../loaders/helpers/resolve-plugins" +import { runMigrationScripts } from "./run-scripts" const TERMINAL_SIZE = process.stdout.columns @@ -21,11 +22,13 @@ const TERMINAL_SIZE = process.stdout.columns export async function migrate({ directory, skipLinks, + skipScripts, executeAllLinks, executeSafeLinks, }: { directory: string skipLinks: boolean + skipScripts: boolean executeAllLinks: boolean executeSafeLinks: boolean }): Promise { @@ -69,12 +72,24 @@ export async function migrate({ }) } + if (!skipScripts) { + /** + * Run migration scripts + */ + console.log(new Array(TERMINAL_SIZE).join("-")) + await runMigrationScripts({ + directory, + container, + }) + } + return true } const main = async function ({ directory, skipLinks, + skipScripts, executeAllLinks, executeSafeLinks, }) { @@ -82,6 +97,7 @@ const main = async function ({ const migrated = await migrate({ directory, skipLinks, + skipScripts, executeAllLinks, executeSafeLinks, }) diff --git a/packages/medusa/src/commands/db/run-scripts.ts b/packages/medusa/src/commands/db/run-scripts.ts new file mode 100644 index 0000000000000..60d7cc4468ece --- /dev/null +++ b/packages/medusa/src/commands/db/run-scripts.ts @@ -0,0 +1,112 @@ +import { MedusaAppLoader } from "@medusajs/framework" +import { LinkLoader } from "@medusajs/framework/links" +import { logger } from "@medusajs/framework/logger" +import { MigrationScriptsMigrator } from "@medusajs/framework/migrations" +import { + ContainerRegistrationKeys, + mergePluginModules, +} from "@medusajs/framework/utils" +import { dirname, join } from "path" + +import { MedusaModule } from "@medusajs/framework/modules-sdk" +import { MedusaContainer } from "@medusajs/types" +import { initializeContainer } from "../../loaders" +import { getResolvedPlugins } from "../../loaders/helpers/resolve-plugins" +import { ensureDbExists } from "../utils" + +const TERMINAL_SIZE = process.stdout.columns + +/** + * A low-level utility to migrate the migration scripts. This util should + * never exit the process implicitly. + */ +export async function runMigrationScripts({ + directory, + container, +}: { + directory: string + container?: MedusaContainer +}): Promise { + /** + * Clear all module instances to prevent cache from kicking in + */ + MedusaModule.clearInstances() + + let container_: MedusaContainer = container! + let onApplicationPrepareShutdown: () => Promise = async () => + Promise.resolve() + let onApplicationShutdown: () => Promise = async () => Promise.resolve() + + try { + /** + * Setup + */ + container_ ??= await initializeContainer(directory) + await ensureDbExists(container_) + + const configModule = container_.resolve( + ContainerRegistrationKeys.CONFIG_MODULE + ) + + const plugins = await getResolvedPlugins(directory, configModule, true) + + mergePluginModules(configModule, plugins) + + const linksSourcePaths = plugins.map((plugin) => + join(plugin.resolve, "links") + ) + await new LinkLoader(linksSourcePaths).load() + + const medusaAppResources = await new MedusaAppLoader().load() + onApplicationPrepareShutdown = + medusaAppResources.onApplicationPrepareShutdown + onApplicationShutdown = medusaAppResources.onApplicationShutdown + await medusaAppResources.onApplicationStart() + + const scriptsSourcePaths = [ + join(dirname(require.resolve("@medusajs/medusa")), "migration-scripts"), + ...plugins.map((plugin) => join(plugin.resolve, "migration-scripts")), + ] + + const migrator = new MigrationScriptsMigrator({ container: container_ }) + await migrator.ensureMigrationsTable() + const pendingScripts = await migrator.getPendingMigrations( + scriptsSourcePaths + ) + + if (!pendingScripts?.length) { + logger.info("No pending migration scripts to execute") + return true + } + + console.log(new Array(TERMINAL_SIZE).join("-")) + logger.info("Pending migration scripts to execute") + logger.info(`${pendingScripts.join("\n")}`) + + console.log(new Array(TERMINAL_SIZE).join("-")) + logger.info("Running migration scripts...") + await migrator.run(scriptsSourcePaths) + + console.log(new Array(TERMINAL_SIZE).join("-")) + logger.info("Migration scripts completed") + + return true + } finally { + await onApplicationPrepareShutdown() + await onApplicationShutdown() + } +} + +const main = async function ({ directory }: { directory: string }) { + try { + const migrated = await runMigrationScripts({ + directory, + }) + process.exit(migrated ? 0 : 1) + } catch (error) { + logger.error(error) + process.exit(1) + } +} + +export default main diff --git a/packages/medusa/src/commands/db/setup.ts b/packages/medusa/src/commands/db/setup.ts index df64824a47135..9a8c837a36e47 100644 --- a/packages/medusa/src/commands/db/setup.ts +++ b/packages/medusa/src/commands/db/setup.ts @@ -7,6 +7,7 @@ const main = async function ({ interactive, db, skipLinks, + skipScripts, executeAllLinks, executeSafeLinks, }) { @@ -19,6 +20,7 @@ const main = async function ({ const migrated = await migrate({ directory, skipLinks, + skipScripts, executeAllLinks, executeSafeLinks, }) diff --git a/www/apps/book/app/learn/fundamentals/modules/db-operations/page.mdx b/www/apps/book/app/learn/fundamentals/modules/db-operations/page.mdx index b4c7bdd9c0ba2..641eeabde59a2 100644 --- a/www/apps/book/app/learn/fundamentals/modules/db-operations/page.mdx +++ b/www/apps/book/app/learn/fundamentals/modules/db-operations/page.mdx @@ -227,7 +227,7 @@ class HelloModuleService { }, @MedusaContext() sharedContext?: Context ): Promise { - anotherMethod(sharedContext) + this.anotherMethod(sharedContext) } } ``` @@ -286,7 +286,7 @@ type InjectedDependencies = { class HelloModuleService { protected baseRepository_: DAL.RepositoryService - constructor({ manager }: InjectedDependencies) { + constructor({ baseRepository }: InjectedDependencies) { this.baseRepository_ = baseRepository } }