feat: Admin Returns API (#8117)

* feat: Add request item + add shipping APIs

* wip

* finalize workflow

* move steps

* add returns to js-sdk

* few chores

* fix test

* fix another test :)

packages/medusa/src/api/admin/returns/[id]/request-items/route.ts

@@ -0,0 +1,40 @@
+import { requestItemReturnWorkflow } from "@medusajs/core-flows"
+import {
+  ContainerRegistrationKeys,
+  remoteQueryObjectFromString,
+} from "@medusajs/utils"
+import {
+  AuthenticatedMedusaRequest,
+  MedusaResponse,
+} from "../../../../../types/routing"
+import { AdminPostReturnsRequestItemsReqSchemaType } from "../../validators"
+
+export const POST = async (
+  req: AuthenticatedMedusaRequest<AdminPostReturnsRequestItemsReqSchemaType>,
+  res: MedusaResponse
+) => {
+  const { id } = req.params
+
+  const remoteQuery = req.scope.resolve(ContainerRegistrationKeys.REMOTE_QUERY)
+
+  await requestItemReturnWorkflow(req.scope).run({
+    input: { ...req.validatedBody, return_id: id },
+  })
+
+  const queryObject = remoteQueryObjectFromString({
+    entryPoint: "return",
+    variables: {
+      id,
+      filters: {
+        ...req.filterableFields,
+      },
+    },
+    fields: req.remoteQueryConfig.fields,
+  })
+
+  const [orderReturn] = await remoteQuery(queryObject)
+
+  res.json({
+    return: orderReturn,
+  })
+}

packages/medusa/src/api/admin/returns/[id]/request/route.ts

@@ -0,0 +1,40 @@
+import { confirmReturnRequestWorkflow } from "@medusajs/core-flows"
+import {
+  ContainerRegistrationKeys,
+  remoteQueryObjectFromString,
+} from "@medusajs/utils"
+import {
+  AuthenticatedMedusaRequest,
+  MedusaResponse,
+} from "../../../../../types/routing"
+import { AdminPostReturnsConfirmRequestReqSchemaType } from "../../validators"
+
+export const POST = async (
+  req: AuthenticatedMedusaRequest<AdminPostReturnsConfirmRequestReqSchemaType>,
+  res: MedusaResponse
+) => {
+  const { id } = req.params
+
+  const remoteQuery = req.scope.resolve(ContainerRegistrationKeys.REMOTE_QUERY)
+
+  await confirmReturnRequestWorkflow(req.scope).run({
+    input: { return_id: id },
+  })
+
+  const queryObject = remoteQueryObjectFromString({
+    entryPoint: "return",
+    variables: {
+      id,
+      filters: {
+        ...req.filterableFields,
+      },
+    },
+    fields: req.remoteQueryConfig.fields,
+  })
+
+  const [orderReturn] = await remoteQuery(queryObject)
+
+  res.json({
+    return: orderReturn,
+  })
+}

packages/medusa/src/api/admin/returns/[id]/shipping-method/route.ts

@@ -0,0 +1,40 @@
+import { createReturnShippingMethodWorkflow } from "@medusajs/core-flows"
+import {
+  ContainerRegistrationKeys,
+  remoteQueryObjectFromString,
+} from "@medusajs/utils"
+import {
+  AuthenticatedMedusaRequest,
+  MedusaResponse,
+} from "../../../../../types/routing"
+import { AdminPostReturnsShippingReqSchemaType } from "../../validators"
+
+export const POST = async (
+  req: AuthenticatedMedusaRequest<AdminPostReturnsShippingReqSchemaType>,
+  res: MedusaResponse
+) => {
+  const { id } = req.params
+
+  const remoteQuery = req.scope.resolve(ContainerRegistrationKeys.REMOTE_QUERY)
+
+  await createReturnShippingMethodWorkflow(req.scope).run({
+    input: { ...req.validatedBody, return_id: id },
+  })
+
+  const queryObject = remoteQueryObjectFromString({
+    entryPoint: "return",
+    variables: {
+      id,
+      filters: {
+        ...req.filterableFields,
+      },
+    },
+    fields: req.remoteQueryConfig.fields,
+  })
+
+  const [orderReturn] = await remoteQuery(queryObject)
+
+  res.json({
+    return: orderReturn,
+  })
+}

packages/medusa/src/api/admin/returns/middlewares.ts

@@ -5,7 +5,10 @@ import * as QueryConfig from "./query-config"
 import {
   AdminGetOrdersOrderParams,
   AdminGetOrdersParams,
+  AdminPostReturnsConfirmRequestReqSchema,
   AdminPostReturnsReqSchema,
+  AdminPostReturnsRequestItemsReqSchema,
+  AdminPostReturnsShippingReqSchema,
 } from "./validators"
 
 export const adminReturnRoutesMiddlewares: MiddlewareRoute[] = [
@@ -40,4 +43,37 @@ export const adminReturnRoutesMiddlewares: MiddlewareRoute[] = [
       ),
     ],
   },
+  {
+    method: ["POST"],
+    matcher: "/admin/returns/:id/request-items",
+    middlewares: [
+      validateAndTransformBody(AdminPostReturnsRequestItemsReqSchema),
+      validateAndTransformQuery(
+        AdminGetOrdersOrderParams,
+        QueryConfig.retrieveTransformQueryConfig
+      ),
+    ],
+  },
+  {
+    method: ["POST"],
+    matcher: "/admin/returns/:id/shipping-method",
+    middlewares: [
+      validateAndTransformBody(AdminPostReturnsShippingReqSchema),
+      validateAndTransformQuery(
+        AdminGetOrdersOrderParams,
+        QueryConfig.retrieveTransformQueryConfig
+      ),
+    ],
+  },
+  {
+    method: ["POST"],
+    matcher: "/admin/returns/:id/request",
+    middlewares: [
+      validateAndTransformBody(AdminPostReturnsConfirmRequestReqSchema),
+      validateAndTransformQuery(
+        AdminGetOrdersOrderParams,
+        QueryConfig.retrieveTransformQueryConfig
+      ),
+    ],
+  },
 ]

packages/medusa/src/api/admin/returns/query-config.ts

@@ -1,62 +1,25 @@
-export const defaultAdminOrderFields = [
+export const defaultAdminReturnFields = [
   "id",
+  "order_id",
+  "exchange_id",
+  "claim_id",
   "display_id",
+  "order_version",
   "status",
-  "version",
-  "summary",
-  "metadata",
-  "created_at",
-  "updated_at",
-]
-
-export const defaultAdminRetrieveOrderFields = [
-  "id",
-  "display_id",
-  "status",
-  "version",
-  "summary",
-  "total",
-  "subtotal",
-  "tax_total",
-  "discount_total",
-  "discount_tax_total",
-  "original_total",
-  "original_tax_total",
-  "item_total",
-  "item_subtotal",
-  "item_tax_total",
-  "original_item_total",
-  "original_item_subtotal",
-  "original_item_tax_total",
-  "shipping_total",
-  "shipping_subtotal",
-  "shipping_tax_total",
-  "original_shipping_tax_total",
-  "original_shipping_tax_subtotal",
-  "original_shipping_total",
+  "refund_amount",
   "created_at",
   "updated_at",
   "*items",
-  "*items.tax_lines",
-  "*items.adjustments",
-  "*items.variant",
-  "*items.variant.product",
-  "*items.detail",
-  "*shipping_address",
-  "*billing_address",
   "*shipping_methods",
-  "*shipping_methods.tax_lines",
-  "*shipping_methods.adjustments",
-  "*payment_collections",
 ]
 
 export const retrieveTransformQueryConfig = {
-  defaultFields: defaultAdminRetrieveOrderFields,
+  defaultFields: defaultAdminReturnFields,
   isList: false,
 }
 
 export const listTransformQueryConfig = {
-  defaults: defaultAdminOrderFields,
+  defaults: defaultAdminReturnFields,
   defaultLimit: 20,
   isList: true,
 }

packages/medusa/src/api/admin/returns/route.ts

@@ -41,11 +41,25 @@ export const POST = async (
   res: MedusaResponse
 ) => {
   const input = req.validatedBody as AdminPostReturnsReqSchemaType
+  const remoteQuery = req.scope.resolve(ContainerRegistrationKeys.REMOTE_QUERY)
 
   const workflow = beginReturnOrderWorkflow(req.scope)
   const { result } = await workflow.run({
     input,
   })
 
-  res.status(200).json({ return: result })
+  const queryObject = remoteQueryObjectFromString({
+    entryPoint: "return",
+    variables: {
+      id: result.return_id,
+      filters: {
+        ...req.filterableFields,
+      },
+    },
+    fields: req.remoteQueryConfig.fields,
+  })
+
+  const [orderReturn] = await remoteQuery(queryObject)
+
+  res.status(200).json({ return: orderReturn })
 }

packages/medusa/src/api/admin/returns/validators.ts

@@ -47,8 +47,10 @@ const ItemSchema = z.object({
 
 export const AdminPostReturnsReqSchema = z.object({
   order_id: z.string(),
+  location_id: z.string().optional(),
   description: z.string().optional(),
   internal_note: z.string().optional(),
+  no_notification: z.boolean().optional(),
   metadata: z.record(z.unknown()).nullish(),
 })
 export type AdminPostReturnsReqSchemaType = z.infer<
@@ -93,3 +95,39 @@ export const AdminPostCancelReturnReqSchema = z.object({
 export type AdminPostCancelReturnReqSchemaType = z.infer<
   typeof AdminPostReceiveReturnsReqSchema
 >
+
+export const AdminPostReturnsShippingReqSchema = z.object({
+  shipping_option_id: z.string(),
+  custom_price: z.number().optional(),
+  description: z.string().optional(),
+  internal_note: z.string().optional(),
+  metadata: z.record(z.unknown()).optional(),
+})
+
+export type AdminPostReturnsShippingReqSchemaType = z.infer<
+  typeof AdminPostReturnsShippingReqSchema
+>
+
+export const AdminPostReturnsRequestItemsReqSchema = z.object({
+  items: z.array(
+    z.object({
+      id: z.string(),
+      quantity: z.number(),
+      description: z.string().optional(),
+      internal_note: z.string().optional(),
+      metadata: z.record(z.unknown()).optional(),
+    })
+  ),
+})
+
+export type AdminPostReturnsRequestItemsReqSchemaType = z.infer<
+  typeof AdminPostReturnsRequestItemsReqSchema
+>
+
+export const AdminPostReturnsConfirmRequestReqSchema = z.object({
+  no_notification: z.boolean().optional(),
+})
+
+export type AdminPostReturnsConfirmRequestReqSchemaType = z.infer<
+  typeof AdminPostReturnsConfirmRequestReqSchema
+>