feat(core-flows,medusa,types): fulfillment API: create (#7101)

what:

- adds fulfillment create API

RESOLVES CORE-1962

packages/medusa/src/api-v2/admin/fulfillments/[id]/shipment/route.ts

@@ -0,0 +1,31 @@
+import { createShipmentWorkflow } from "@medusajs/core-flows"
+import {
+  AuthenticatedMedusaRequest,
+  MedusaResponse,
+} from "../../../../../types/routing"
+import { refetchFulfillment } from "../../helpers"
+import { AdminCreateShipmentType } from "../../validators"
+
+export const POST = async (
+  req: AuthenticatedMedusaRequest<AdminCreateShipmentType>,
+  res: MedusaResponse
+) => {
+  const { id } = req.params
+
+  const { errors } = await createShipmentWorkflow(req.scope).run({
+    input: { id, ...req.validatedBody },
+    throwOnError: false,
+  })
+
+  if (Array.isArray(errors) && errors[0]) {
+    throw errors[0].error
+  }
+
+  const fulfillment = await refetchFulfillment(
+    id,
+    req.scope,
+    req.remoteQueryConfig.fields
+  )
+
+  res.status(200).json({ fulfillment })
+}

packages/medusa/src/api-v2/admin/fulfillments/middlewares.ts

@@ -3,7 +3,12 @@ import { authenticate } from "../../../utils/authenticate-middleware"
 import { validateAndTransformBody } from "../../utils/validate-body"
 import { validateAndTransformQuery } from "../../utils/validate-query"
 import * as QueryConfig from "./query-config"
-import { AdminCancelFulfillment, AdminFulfillmentParams } from "./validators"
+import {
+  AdminCancelFulfillment,
+  AdminCreateFulfillment,
+  AdminCreateShipment,
+  AdminFulfillmentParams,
+} from "./validators"
 
 export const adminFulfillmentsRoutesMiddlewares: MiddlewareRoute[] = [
   {
@@ -22,4 +27,26 @@ export const adminFulfillmentsRoutesMiddlewares: MiddlewareRoute[] = [
       ),
     ],
   },
+  {
+    method: ["POST"],
+    matcher: "/admin/fulfillments",
+    middlewares: [
+      validateAndTransformBody(AdminCreateFulfillment),
+      validateAndTransformQuery(
+        AdminFulfillmentParams,
+        QueryConfig.retrieveTransformQueryConfig
+      ),
+    ],
+  },
+  {
+    method: ["POST"],
+    matcher: "/admin/fulfillments/:id/shipment",
+    middlewares: [
+      validateAndTransformBody(AdminCreateShipment),
+      validateAndTransformQuery(
+        AdminFulfillmentParams,
+        QueryConfig.retrieveTransformQueryConfig
+      ),
+    ],
+  },
 ]

packages/medusa/src/api-v2/admin/fulfillments/query-config.ts

@@ -9,8 +9,13 @@ export const defaultAdminFulfillmentsFields = [
   "provider_id",
   "shipping_option_id",
   "metadata",
+  "order",
   "created_at",
   "updated_at",
+  "deleted_at",
+  "*delivery_address",
+  "*items",
+  "*labels",
 ]
 
 export const retrieveTransformQueryConfig = {

packages/medusa/src/api-v2/admin/fulfillments/route.ts

@@ -0,0 +1,31 @@
+import { createFulfillmentWorkflow } from "@medusajs/core-flows"
+import {
+  AuthenticatedMedusaRequest,
+  MedusaResponse,
+} from "../../../types/routing"
+import { refetchFulfillment } from "./helpers"
+import { AdminCreateFulfillmentType } from "./validators"
+
+export const POST = async (
+  req: AuthenticatedMedusaRequest<AdminCreateFulfillmentType>,
+  res: MedusaResponse
+) => {
+  const { result: fullfillment, errors } = await createFulfillmentWorkflow(
+    req.scope
+  ).run({
+    input: req.validatedBody,
+    throwOnError: false,
+  })
+
+  if (Array.isArray(errors) && errors[0]) {
+    throw errors[0].error
+  }
+
+  const fulfillment = await refetchFulfillment(
+    fullfillment.id,
+    req.scope,
+    req.remoteQueryConfig.fields
+  )
+
+  res.status(200).json({ fulfillment })
+}

packages/medusa/src/api-v2/admin/fulfillments/validators.ts

@@ -1,7 +1,39 @@
 import { z } from "zod"
+import { AddressPayload } from "../../utils/common-validators"
 import { createSelectParams } from "../../utils/validators"
 
 export const AdminFulfillmentParams = createSelectParams()
 
-export const AdminCancelFulfillment = z.object({})
+const AdminCreateFulfillmentItem = z.object({
+  title: z.string(),
+  sku: z.string(),
+  quantity: z.number(),
+  barcode: z.string(),
+  line_item_id: z.string().optional(),
+  inventory_item_id: z.string().optional(),
+})
+
+const AdminCreateFulfillmentLabel = z.object({
+  tracking_number: z.string(),
+  tracking_url: z.string(),
+  label_url: z.string(),
+})
+
 export type AdminCancelFulfillmentType = z.infer<typeof AdminCancelFulfillment>
+export const AdminCancelFulfillment = z.object({})
+
+export type AdminCreateFulfillmentType = z.infer<typeof AdminCreateFulfillment>
+export const AdminCreateFulfillment = z.object({
+  location_id: z.string(),
+  provider_id: z.string(),
+  delivery_address: AddressPayload,
+  items: z.array(AdminCreateFulfillmentItem),
+  labels: z.array(AdminCreateFulfillmentLabel),
+  order: z.object({}),
+  metadata: z.record(z.unknown()).optional().nullable(),
+})
+
+export type AdminCreateShipmentType = z.infer<typeof AdminCreateShipment>
+export const AdminCreateShipment = z.object({
+  labels: z.array(AdminCreateFulfillmentLabel),
+})

packages/medusa/src/api-v2/utils/common-validators.ts

@@ -12,7 +12,7 @@ export const AddressPayload = z
     country_code: z.string().optional(),
     province: z.string().optional(),
     postal_code: z.string().optional(),
-    metadata: z.record(z.string()).optional(),
+    metadata: z.record(z.string()).optional().nullable(),
   })
   .strict()