feat(medusa,core-flows,types,js-sdk): decline / cancel order transfer (#10202)

**What**
- **core-flows**: 
  - cancel transfer
  - decline transfer
- **API**:
  - admin cancel transfer
  - store decline transfer 
  - store cancel transfer
- **js-sdk**:
  - add methods for store endpoints 

---

CLOSES CMRC-726

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

@@ -80,3 +80,5 @@ export * from "./update-order-changes"
 export * from "./update-tax-lines"
 export * from "./transfer/request-order-transfer"
 export * from "./transfer/accept-order-transfer"
+export * from "./transfer/cancel-order-transfer"
+export * from "./transfer/decline-order-transfer"

packages/core/core-flows/src/order/workflows/order-edit/cancel-begin-order-edit.ts

@@ -41,7 +41,9 @@ export const cancelBeginOrderEditWorkflowId = "cancel-begin-order-edit"
  */
 export const cancelBeginOrderEditWorkflow = createWorkflow(
   cancelBeginOrderEditWorkflowId,
-  function (input: CancelBeginOrderEditWorkflowInput): WorkflowData<void> {
+  function (
+    input: WorkflowData<CancelBeginOrderEditWorkflowInput>
+  ): WorkflowData<void> {
     const order: OrderDTO = useRemoteQueryStep({
       entry_point: "orders",
       fields: ["id", "version", "canceled_at"],

packages/core/core-flows/src/order/workflows/transfer/accept-order-transfer.ts

@@ -8,17 +8,18 @@ import {
   WorkflowResponse,
   createStep,
   createWorkflow,
+  transform,
 } from "@medusajs/framework/workflows-sdk"
 import { OrderPreviewDTO } from "@medusajs/types"
-
-import { useRemoteQueryStep } from "../../../common"
-import { throwIfOrderIsCancelled } from "../../utils/order-validation"
-import { previewOrderChangeStep } from "../../steps"
 import {
   ChangeActionType,
   MedusaError,
   OrderChangeStatus,
 } from "@medusajs/utils"
+
+import { useQueryGraphStep } from "../../../common"
+import { throwIfOrderIsCancelled } from "../../utils/order-validation"
+import { previewOrderChangeStep } from "../../steps"
 import { confirmOrderChanges } from "../../steps/confirm-order-changes"
 
 /**
@@ -62,16 +63,20 @@ export const acceptOrderTransferWorkflow = createWorkflow(
   function (
     input: WorkflowData<OrderWorkflow.AcceptOrderTransferWorkflowInput>
   ): WorkflowResponse<OrderPreviewDTO> {
-    const order: OrderDTO = useRemoteQueryStep({
-      entry_point: "orders",
+    const orderQuery = useQueryGraphStep({
+      entity: "order",
       fields: ["id", "email", "status", "customer_id"],
-      variables: { id: input.order_id },
-      list: false,
-      throw_if_key_not_found: true,
-    })
+      filters: { id: input.order_id },
+      options: { throwIfKeyNotFound: true },
+    }).config({ name: "order-query" })
 
-    const orderChange: OrderChangeDTO = useRemoteQueryStep({
-      entry_point: "order_change",
+    const order = transform(
+      { orderQuery },
+      ({ orderQuery }) => orderQuery.data[0]
+    )
+
+    const orderChangeQuery = useQueryGraphStep({
+      entity: "order_change",
       fields: [
         "id",
         "status",
@@ -84,15 +89,18 @@ export const acceptOrderTransferWorkflow = createWorkflow(
         "actions.reference_id",
         "actions.internal_note",
       ],
-      variables: {
-        filters: {
-          order_id: input.order_id,
-          status: [OrderChangeStatus.REQUESTED],
-        },
+      filters: {
+        order_id: input.order_id,
+        status: [OrderChangeStatus.REQUESTED],
       },
-      list: false,
+      options: { throwIfKeyNotFound: true },
     }).config({ name: "order-change-query" })
 
+    const orderChange = transform(
+      { orderChangeQuery },
+      ({ orderChangeQuery }) => orderChangeQuery.data[0]
+    )
+
     acceptOrderTransferValidationStep({
       order,
       orderChange,

packages/core/core-flows/src/order/workflows/transfer/cancel-order-transfer.ts

@@ -0,0 +1,101 @@
+import {
+  OrderChangeDTO,
+  OrderDTO,
+  OrderWorkflow,
+} from "@medusajs/framework/types"
+import {
+  ChangeActionType,
+  MedusaError,
+  OrderChangeStatus,
+} from "@medusajs/framework/utils"
+import {
+  WorkflowData,
+  createStep,
+  createWorkflow,
+  transform,
+} from "@medusajs/framework/workflows-sdk"
+import { useQueryGraphStep } from "../../../common"
+import { deleteOrderChangesStep } from "../../steps"
+import {
+  throwIfIsCancelled,
+  throwIfOrderChangeIsNotActive,
+} from "../../utils/order-validation"
+
+/**
+ * This step validates that a requested order transfer can be canceled.
+ */
+export const cancelTransferOrderRequestValidationStep = createStep(
+  "validate-cancel-transfer-order-request",
+  async function ({
+    order,
+    orderChange,
+    input,
+  }: {
+    order: OrderDTO
+    orderChange: OrderChangeDTO
+    input: OrderWorkflow.CancelTransferOrderRequestWorkflowInput
+  }) {
+    throwIfIsCancelled(order, "Order")
+    throwIfOrderChangeIsNotActive({ orderChange })
+
+    if (input.actor_type === "user") {
+      return
+    }
+
+    const action = orderChange.actions?.find(
+      (a) => a.action === ChangeActionType.TRANSFER_CUSTOMER
+    )
+
+    if (action?.reference_id !== input.logged_in_user_id) {
+      throw new MedusaError(
+        MedusaError.Types.NOT_ALLOWED,
+        "This customer is not allowed to cancel the transfer."
+      )
+    }
+  }
+)
+
+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.
+ */
+export const cancelOrderTransferRequestWorkflow = createWorkflow(
+  cancelTransferOrderRequestWorkflowId,
+  function (
+    input: WorkflowData<OrderWorkflow.CancelTransferOrderRequestWorkflowInput>
+  ): WorkflowData<void> {
+    const orderQuery = useQueryGraphStep({
+      entity: "order",
+      fields: ["id", "version", "canceled_at"],
+      filters: { id: input.order_id },
+      options: { throwIfKeyNotFound: true },
+    }).config({ name: "order-query" })
+
+    const order = transform(
+      { orderQuery },
+      ({ orderQuery }) => orderQuery.data[0]
+    )
+
+    const orderChangeQuery = useQueryGraphStep({
+      entity: "order_change",
+      fields: ["id", "status", "version", "actions.*"],
+      filters: {
+        order_id: input.order_id,
+        status: [OrderChangeStatus.PENDING, OrderChangeStatus.REQUESTED],
+      },
+      options: { throwIfKeyNotFound: true },
+    }).config({ name: "order-change-query" })
+
+    const orderChange = transform(
+      { orderChangeQuery },
+      ({ orderChangeQuery }) => orderChangeQuery.data[0]
+    )
+
+    cancelTransferOrderRequestValidationStep({ order, orderChange, input })
+
+    deleteOrderChangesStep({ ids: [orderChange.id] })
+  }
+)

packages/core/core-flows/src/order/workflows/transfer/decline-order-transfer.ts

@@ -0,0 +1,95 @@
+import {
+  OrderChangeDTO,
+  OrderDTO,
+  OrderWorkflow,
+} from "@medusajs/framework/types"
+import {
+  ChangeActionType,
+  MedusaError,
+  OrderChangeStatus,
+} from "@medusajs/framework/utils"
+import {
+  WorkflowData,
+  createStep,
+  createWorkflow,
+  transform,
+} from "@medusajs/framework/workflows-sdk"
+
+import { useQueryGraphStep } from "../../../common"
+import { declineOrderChangeStep } from "../../steps"
+import {
+  throwIfIsCancelled,
+  throwIfOrderChangeIsNotActive,
+} from "../../utils/order-validation"
+
+/**
+ * This step validates that a requested order transfer can be declineed.
+ */
+export const declineTransferOrderRequestValidationStep = createStep(
+  "validate-decline-transfer-order-request",
+  async function ({
+    order,
+    orderChange,
+    input,
+  }: {
+    order: OrderDTO
+    orderChange: OrderChangeDTO
+    input: OrderWorkflow.DeclineTransferOrderRequestWorkflowInput
+  }) {
+    throwIfIsCancelled(order, "Order")
+    throwIfOrderChangeIsNotActive({ orderChange })
+
+    const token = orderChange.actions?.find(
+      (a) => a.action === ChangeActionType.TRANSFER_CUSTOMER
+    )?.details!.token
+
+    if (!input.token?.length || token !== input.token) {
+      throw new MedusaError(MedusaError.Types.NOT_ALLOWED, "Invalid token.")
+    }
+  }
+)
+
+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.
+ */
+export const declineOrderTransferRequestWorkflow = createWorkflow(
+  declineTransferOrderRequestWorkflowId,
+  function (
+    input: WorkflowData<OrderWorkflow.DeclineTransferOrderRequestWorkflowInput>
+  ): WorkflowData<void> {
+    const orderQuery = useQueryGraphStep({
+      entity: "order",
+      fields: ["id", "version", "declineed_at"],
+      filters: { id: input.order_id },
+      options: { throwIfKeyNotFound: true },
+    }).config({ name: "order-query" })
+
+    const order = transform(
+      { orderQuery },
+      ({ orderQuery }) => orderQuery.data[0]
+    )
+
+    const orderChangeQuery = useQueryGraphStep({
+      entity: "order_change",
+      fields: ["id", "status", "version", "actions.*"],
+      filters: {
+        order_id: input.order_id,
+        status: [OrderChangeStatus.PENDING, OrderChangeStatus.REQUESTED],
+      },
+      options: { throwIfKeyNotFound: true },
+    }).config({ name: "order-change-query" })
+
+    const orderChange = transform(
+      { orderChangeQuery },
+      ({ orderChangeQuery }) => orderChangeQuery.data[0]
+    )
+
+    declineTransferOrderRequestValidationStep({ order, orderChange, input })
+
+    declineOrderChangeStep({ id: orderChange.id })
+  }
+)

packages/core/core-flows/src/order/workflows/transfer/request-order-transfer.ts

@@ -131,7 +131,7 @@ export const requestOrderTransferWorkflow = createWorkflow(
 
     emitEventStep({
       eventName: OrderWorkflowEvents.TRANSFER_REQUESTED,
-      data: { id: input.order_id },
+      data: { id: input.order_id, order_change_id: change.id },
     })
 
     return new WorkflowResponse(previewOrderChangeStep(input.order_id))

packages/core/js-sdk/src/store/index.ts

@@ -1077,6 +1077,162 @@ export class Store {
         }
       )
     },
+
+    /**
+     * This method requests a order transfer from a guest account to the current, logged in customer account.
+     *
+     * Customer requesting the transfer must be logged in.
+     *
+     * @param body - The transfer's details.
+     * @param query - Configure the fields to retrieve in the order.
+     * @param headers - Headers to pass in the request.
+     * @returns The order details.
+     *
+     * @example
+     * sdk.store.order.requestTransfer(
+     *   "order_123",
+     *   {
+     *     description: "I want to transfer this order to my friend."
+     *   },
+     *   {},
+     *   {
+     *     Authorization: `Bearer ${token}`
+     *   }
+     * )
+     * .then(({ order }) => {
+     *   console.log(order)
+     * })
+     */
+    requestTransfer: async (
+      id: string,
+      body: HttpTypes.StoreRequestOrderTransfer,
+      query?: SelectParams,
+      headers?: ClientHeaders
+    ) => {
+      return this.client.fetch<HttpTypes.StoreOrderResponse>(
+        `/store/orders/${id}/transfer/request`,
+        {
+          method: "POST",
+          headers,
+          body,
+          query,
+        }
+      )
+    },
+    /**
+     * This method cancels an order transfer request.
+     *
+     * Customer requesting the transfer must be logged in.
+     *
+     * @param id - The order's ID.
+     * @param query - Configure the fields to retrieve in the order.
+     * @param headers - Headers to pass in the request.
+     * @returns The order details.
+     *
+     * @example
+     * sdk.store.order.cancelTransfer(
+     *   "order_123",
+     *   {},
+     *   {
+     *     Authorization: `Bearer ${token}`
+     *   }
+     * )
+     * .then(({ order }) => {
+     *   console.log(order)
+     * })
+     */
+    cancelTransfer: async (
+      id: string,
+      query?: SelectParams,
+      headers?: ClientHeaders
+    ) => {
+      return this.client.fetch<HttpTypes.StoreOrderResponse>(
+        `/store/orders/${id}/transfer/cancel`,
+        {
+          method: "POST",
+          headers,
+          query,
+        }
+      )
+    },
+    /**
+     * The method called for the original owner to accept the order transfer to a new owner.
+     *
+     * @param id - The order's ID.
+     * @param body - The payload containing the transfer token.
+     * @param query - Configure the fields to retrieve in the order.
+     * @param headers - Headers to pass in the request.
+     * @returns The order details.
+     *
+     * @example
+     * sdk.store.order.acceptTransfer(
+     *   "order_123",
+     *   {
+     *     token: "transfer_token"
+     *   },
+     *   {
+     *     Authorization: `Bearer ${token}`
+     *   }
+     * )
+     * .then(({ order }) => {
+     *   console.log(order)
+     * })
+     */
+    acceptTransfer: async (
+      id: string,
+      body: HttpTypes.StoreAcceptOrderTransfer,
+      query?: SelectParams,
+      headers?: ClientHeaders
+    ) => {
+      return this.client.fetch<HttpTypes.StoreOrderResponse>(
+        `/store/orders/${id}/transfer/accept`,
+        {
+          method: "POST",
+          headers,
+          body,
+          query,
+        }
+      )
+    },
+    /**
+     * The method called for the original owner to decline the order transfer to a new owner.
+     *
+     * @param id - The order's ID.
+     * @param body - The payload containing the transfer token.
+     * @param query - Configure the fields to retrieve in the order.
+     * @param headers - Headers to pass in the request.
+     * @returns The order details.
+     *
+     * @example
+     * sdk.store.order.declineTransfer(
+     *   "order_123",
+     *   {
+     *     token: "transfer_token"
+     *   },
+     *   {
+     *     Authorization: `Bearer ${token}`
+     *   }
+     * )
+     * .then(({ order }) => {
+     *   console.log(order)
+     * })
+     */
+    declineTransfer: async (
+      id: string,
+      body: HttpTypes.StoreDeclineOrderTransfer,
+      query?: SelectParams,
+      headers?: ClientHeaders
+    ) => {
+      return this.client.fetch<HttpTypes.StoreOrderResponse>(
+        `/store/orders/${id}/transfer/decline`,
+        {
+          method: "POST",
+          headers,
+          body,
+          query,
+        }
+      )
+    },
   }
 
   public customer = {

packages/core/types/src/http/order/store/index.ts

@@ -1,3 +1,4 @@
 export * from "./entities"
 export * from "./queries"
 export * from "./responses"
+export * from "./payloads"

packages/core/types/src/http/order/store/payloads.ts

@@ -0,0 +1,14 @@
+export interface StoreRequestOrderTransfer {
+  /**
+   * The description of the transfer request.
+   */
+  description?: string
+}
+
+export interface StoreAcceptOrderTransfer {
+  token: string
+}
+
+export interface StoreDeclineOrderTransfer {
+  token: string
+}

packages/core/types/src/workflow/order/cancel-transfer.ts

@@ -0,0 +1,5 @@
+export type CancelTransferOrderRequestWorkflowInput = {
+  order_id: string
+  logged_in_user_id: string
+  actor_type: "customer" | "user"
+}

packages/core/types/src/workflow/order/decline-transfer.ts

@@ -0,0 +1,4 @@
+export type DeclineTransferOrderRequestWorkflowInput = {
+  order_id: string
+  token: string
+}

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

@@ -17,3 +17,5 @@ export * from "./shipping-method"
 export * from "./update-return"
 export * from "./request-transfer"
 export * from "./accept-transfer"
+export * from "./cancel-transfer"
+export * from "./decline-transfer"