feat(core-flows,types): add workflow to request item return (#8098)

packages/core/core-flows/src/order/utils/order-validation.ts

@@ -1,5 +1,15 @@
-import { OrderDTO, OrderWorkflow, ReturnDTO } from "@medusajs/types"
-import { MedusaError, OrderStatus, arrayDifference } from "@medusajs/utils"
+import {
+  OrderChangeDTO,
+  OrderDTO,
+  OrderWorkflow,
+  ReturnDTO,
+} from "@medusajs/types"
+import {
+  MedusaError,
+  OrderStatus,
+  arrayDifference,
+  isPresent,
+} from "@medusajs/utils"
 
 export function throwIfOrderIsCancelled({ order }: { order: OrderDTO }) {
   if (order.status === OrderStatus.CANCELED) {
@@ -44,6 +54,30 @@ export function throwIfReturnIsCancelled({
   }
 }
 
+export function throwIfOrderChangeIsNotActive({
+  orderChange,
+}: {
+  orderChange: OrderChangeDTO
+}) {
+  if (!isPresent(orderChange)) {
+    throw new MedusaError(
+      MedusaError.Types.INVALID_DATA,
+      `An active Order Change is required to proceed`
+    )
+  }
+
+  if (
+    orderChange.canceled_at ||
+    orderChange.confirmed_at ||
+    orderChange.declined_at
+  ) {
+    throw new MedusaError(
+      MedusaError.Types.INVALID_DATA,
+      `Order change ${orderChange?.id} is not active to be modified`
+    )
+  }
+}
+
 export function throwIfItemsDoesNotExistsInReturn({
   orderReturn,
   inputItems,

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

@@ -19,5 +19,6 @@ export * from "./delete-order-change-actions"
 export * from "./get-order-detail"
 export * from "./get-orders-list"
 export * from "./receive-return"
+export * from "./request-item-return"
 export * from "./update-order-change-actions"
 export * from "./update-tax-lines"

packages/core/core-flows/src/order/workflows/request-item-return.ts

@@ -0,0 +1,99 @@
+import {
+  OrderChangeActionDTO,
+  OrderChangeDTO,
+  OrderDTO,
+  OrderWorkflow,
+  ReturnDTO,
+} from "@medusajs/types"
+import { ChangeActionType } from "@medusajs/utils"
+import {
+  WorkflowData,
+  createStep,
+  createWorkflow,
+  transform,
+} from "@medusajs/workflows-sdk"
+import { useRemoteQueryStep } from "../../common"
+import { createOrderChangeActionsStep } from "../steps/create-order-change-actions"
+import {
+  throwIfItemsDoesNotExistsInOrder,
+  throwIfOrderChangeIsNotActive,
+  throwIfOrderIsCancelled,
+  throwIfReturnIsCancelled,
+} from "../utils/order-validation"
+
+const validationStep = createStep(
+  "request-item-return-validation",
+  async function ({
+    order,
+    orderChange,
+    orderReturn,
+    items,
+  }: {
+    order: OrderDTO
+    orderReturn: ReturnDTO
+    orderChange: OrderChangeDTO
+    items: OrderWorkflow.RequestItemReturnWorkflowInput["items"]
+  }) {
+    throwIfOrderIsCancelled({ order })
+    throwIfReturnIsCancelled({ orderReturn })
+    throwIfOrderChangeIsNotActive({ orderChange })
+    throwIfItemsDoesNotExistsInOrder({ order, inputItems: items })
+  }
+)
+
+export const requestItemReturnWorkflowId = "request-item-return"
+export const requestItemReturnWorkflow = createWorkflow(
+  requestItemReturnWorkflowId,
+  function (
+    input: WorkflowData<OrderWorkflow.RequestItemReturnWorkflowInput>
+  ): WorkflowData<OrderChangeActionDTO[]> {
+    const orderReturn: ReturnDTO = useRemoteQueryStep({
+      entry_point: "return",
+      fields: ["id", "status", "refund_amount", "order_id", "items.*"],
+      variables: { id: input.return_id },
+      list: false,
+      throw_if_key_not_found: true,
+    })
+
+    const order: OrderDTO = useRemoteQueryStep({
+      entry_point: "orders",
+      fields: ["id", "status", "items.*"],
+      variables: { id: orderReturn.order_id },
+      list: false,
+      throw_if_key_not_found: true,
+    }).config({ name: "order-query" })
+
+    const orderChange: OrderChangeDTO = useRemoteQueryStep({
+      entry_point: "order_change",
+      fields: ["id", "status"],
+      variables: { order_id: orderReturn.order_id },
+      list: false,
+    }).config({ name: "order-change-query" })
+
+    validationStep({ order, items: input.items, orderReturn, orderChange })
+
+    const orderChangeActionInput = transform(
+      { order, orderChange, orderReturn, items: input.items },
+      ({ order, orderChange, orderReturn, items }) => {
+        return items.map((item) => ({
+          order_change_id: orderChange.id,
+          order_id: order.id,
+          return_id: orderReturn.id,
+          version: orderChange.version,
+          action: ChangeActionType.RETURN_ITEM,
+          internal_note: item.internal_note,
+          reference: "return",
+          reference_id: orderReturn.id,
+          details: {
+            reference_id: item.id,
+            return_id: orderReturn.id,
+            quantity: item.quantity,
+            metadata: item.metadata,
+          },
+        }))
+      }
+    )
+
+    return createOrderChangeActionsStep(orderChangeActionInput)
+  }
+)

packages/core/orchestration/src/joiner/remote-joiner.ts

@@ -434,6 +434,7 @@ export class RemoteJoiner {
     })
 
     if (notFound.size > 0) {
+      // TODO: This should say "entryPoint" resource not found and not "serviceName" resource not found
       throw new MedusaError(
         MedusaError.Types.NOT_FOUND,
         `${expand.serviceConfig.serviceName} ${pkField} not found: ` +

packages/core/types/src/order/common.ts

@@ -1141,6 +1141,7 @@ type ReturnStatus = "requested" | "received" | "partially_received" | "canceled"
 export interface ReturnDTO extends Omit<OrderDTO, "status" | "version"> {
   status: ReturnStatus
   refund_amount?: BigNumberValue
+  order_id: string
 }
 
 export interface OrderClaimDTO
@@ -1198,7 +1199,7 @@ export interface OrderChangeDTO {
   /**
    * The version of the order change
    */
-  version: string
+  version: number
   /**
    * The type of the order change
    */

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

@@ -1,6 +1,6 @@
 import { BigNumberInput } from "../../totals"
 
-interface CreateReturnItem {
+export interface CreateReturnItem {
   id: string
   quantity: BigNumberInput
   internal_note?: string | null

packages/core/types/src/workflow/order/index.ts

@@ -10,3 +10,4 @@ export * from "./create-fulfillment"
 export * from "./create-return-order"
 export * from "./create-shipment"
 export * from "./receive-return"
+export * from "./request-item-return"

packages/core/types/src/workflow/order/request-item-return.ts

@@ -0,0 +1,6 @@
+import { CreateReturnItem } from "./create-return-order"
+
+export interface RequestItemReturnWorkflowInput {
+  return_id: string
+  items: CreateReturnItem[]
+}