Feat(medusa, core-flows, types): add reservation endpoints (#7018)

* add reservation endpoints

* add changeset

packages/core-flows/src/index.ts

@@ -16,6 +16,7 @@ export * from "./price-list"
 export * from "./pricing"
 export * from "./product"
 export * from "./promotion"
+export * from "./reservation"
 export * from "./region"
 export * from "./sales-channel"
 export * from "./shipping-options"

packages/core-flows/src/reservation/index.ts

@@ -0,0 +1,2 @@
+export * from "./steps"
+export * from "./workflows"

packages/core-flows/src/reservation/steps/create-reservations.ts

@@ -0,0 +1,32 @@
+import { IInventoryServiceNext, InventoryNext } from "@medusajs/types"
+import { StepResponse, createStep } from "@medusajs/workflows-sdk"
+
+import { ModuleRegistrationName } from "@medusajs/modules-sdk"
+
+export const createReservationsStepId = "create-reservations-step"
+export const createReservationsStep = createStep(
+  createReservationsStepId,
+  async (data: InventoryNext.CreateReservationItemInput[], { container }) => {
+    const service = container.resolve<IInventoryServiceNext>(
+      ModuleRegistrationName.INVENTORY
+    )
+
+    const created = await service.createReservationItems(data)
+
+    return new StepResponse(
+      created,
+      created.map((reservation) => reservation.id)
+    )
+  },
+  async (createdIds, { container }) => {
+    if (!createdIds?.length) {
+      return
+    }
+
+    const service = container.resolve<IInventoryServiceNext>(
+      ModuleRegistrationName.INVENTORY
+    )
+
+    await service.deleteReservationItems(createdIds)
+  }
+)

packages/core-flows/src/reservation/steps/delete-reservations.ts

@@ -0,0 +1,29 @@
+import { StepResponse, createStep } from "@medusajs/workflows-sdk"
+
+import { IInventoryServiceNext } from "@medusajs/types"
+import { ModuleRegistrationName } from "@medusajs/modules-sdk"
+
+export const deleteReservationsStepId = "delete-reservations"
+export const deleteReservationsStep = createStep(
+  deleteReservationsStepId,
+  async (ids: string[], { container }) => {
+    const service = container.resolve<IInventoryServiceNext>(
+      ModuleRegistrationName.INVENTORY
+    )
+
+    await service.softDeleteReservationItems(ids)
+
+    return new StepResponse(void 0, ids)
+  },
+  async (prevIds, { container }) => {
+    if (!prevIds?.length) {
+      return
+    }
+
+    const service = container.resolve<IInventoryServiceNext>(
+      ModuleRegistrationName.INVENTORY
+    )
+
+    await service.restoreReservationItems(prevIds)
+  }
+)

packages/core-flows/src/reservation/steps/index.ts

@@ -0,0 +1,3 @@
+export * from "./create-reservations"
+export * from "./delete-reservations"
+export * from "./update-reservations"

packages/core-flows/src/reservation/steps/update-reservations.ts

@@ -0,0 +1,54 @@
+import {
+  IInventoryServiceNext,
+  InventoryNext,
+  UpdateRuleTypeDTO,
+} from "@medusajs/types"
+import { StepResponse, createStep } from "@medusajs/workflows-sdk"
+import {
+  convertItemResponseToUpdateRequest,
+  getSelectsAndRelationsFromObjectArray,
+} from "@medusajs/utils"
+
+import { ModuleRegistrationName } from "@medusajs/modules-sdk"
+
+export const updateReservationsStepId = "update-reservations-step"
+export const updateReservationsStep = createStep(
+  updateReservationsStepId,
+  async (data: InventoryNext.UpdateReservationItemInput[], { container }) => {
+    const inventoryModuleService = container.resolve<IInventoryServiceNext>(
+      ModuleRegistrationName.INVENTORY
+    )
+
+    const { selects, relations } = getSelectsAndRelationsFromObjectArray(data)
+    const dataBeforeUpdate = await inventoryModuleService.listReservationItems(
+      { id: data.map((d) => d.id) },
+      { relations, select: selects }
+    )
+
+    const updatedReservations =
+      await inventoryModuleService.updateReservationItems(data)
+
+    return new StepResponse(updatedReservations, {
+      dataBeforeUpdate,
+      selects,
+      relations,
+    })
+  },
+  async (revertInput, { container }) => {
+    if (!revertInput) {
+      return
+    }
+
+    const { dataBeforeUpdate = [], selects, relations } = revertInput
+
+    const inventoryModuleService = container.resolve<IInventoryServiceNext>(
+      ModuleRegistrationName.INVENTORY
+    )
+
+    await inventoryModuleService.updateReservationItems(
+      dataBeforeUpdate.map((data) =>
+        convertItemResponseToUpdateRequest(data, selects, relations)
+      )
+    )
+  }
+)

packages/core-flows/src/reservation/workflows/create-reservations.ts

@@ -0,0 +1,14 @@
+import { WorkflowData, createWorkflow } from "@medusajs/workflows-sdk"
+
+import { WorkflowTypes } from "@medusajs/types"
+import { createReservationsStep } from "../steps"
+
+export const createReservationsWorkflowId = "create-reservations-workflow"
+export const createReservationsWorkflow = createWorkflow(
+  createReservationsWorkflowId,
+  (
+    input: WorkflowData<WorkflowTypes.ReservationWorkflow.CreateReservationsWorkflowInput>
+  ): WorkflowData<WorkflowTypes.ReservationWorkflow.CreateReservationsWorkflowOutput> => {
+    return createReservationsStep(input.reservations)
+  }
+)

packages/core-flows/src/reservation/workflows/delete-reservations.ts

@@ -0,0 +1,13 @@
+import { WorkflowData, createWorkflow } from "@medusajs/workflows-sdk"
+
+import { deleteReservationsStep } from "../steps"
+
+type WorkflowInput = { ids: string[] }
+
+export const deleteReservationsWorkflowId = "delete-reservations"
+export const deleteReservationsWorkflow = createWorkflow(
+  deleteReservationsWorkflowId,
+  (input: WorkflowData<WorkflowInput>): WorkflowData<void> => {
+    return deleteReservationsStep(input.ids)
+  }
+)

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

@@ -0,0 +1,3 @@
+export * from "./create-reservations"
+export * from "./delete-reservations"
+export * from "./update-reservations"

packages/core-flows/src/reservation/workflows/update-reservations.ts

@@ -0,0 +1,14 @@
+import { WorkflowData, createWorkflow } from "@medusajs/workflows-sdk"
+
+import { WorkflowTypes } from "@medusajs/types"
+import { updateReservationsStep } from "../steps"
+
+export const updateReservationsWorkflowId = "update-reservations-workflow"
+export const updateReservationsWorkflow = createWorkflow(
+  updateReservationsWorkflowId,
+  (
+    input: WorkflowData<WorkflowTypes.ReservationWorkflow.UpdateReservationsWorkflowInput>
+  ): WorkflowData<WorkflowTypes.ReservationWorkflow.UpdateReservationsWorkflowOutput> => {
+    return updateReservationsStep(input.updates)
+  }
+)

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

@@ -0,0 +1,93 @@
+import {
+  AuthenticatedMedusaRequest,
+  MedusaResponse,
+} from "../../../../types/routing"
+import {
+  ContainerRegistrationKeys,
+  remoteQueryObjectFromString,
+} from "@medusajs/utils"
+
+import { AdminPostReservationsReservationReq } from "../validators"
+import { MedusaError } from "@medusajs/utils"
+import { deleteReservationsWorkflow } from "@medusajs/core-flows"
+import { updateReservationsWorkflow } from "@medusajs/core-flows"
+
+export const GET = async (
+  req: AuthenticatedMedusaRequest,
+  res: MedusaResponse
+) => {
+  const { id } = req.params
+  const remoteQuery = req.scope.resolve("remoteQuery")
+
+  const variables = { id }
+
+  const queryObject = remoteQueryObjectFromString({
+    entryPoint: "reservation",
+    variables,
+    fields: req.remoteQueryConfig.fields,
+  })
+
+  const [reservation] = await remoteQuery(queryObject)
+
+  if (!reservation) {
+    throw new MedusaError(
+      MedusaError.Types.NOT_FOUND,
+      `Reservation with id: ${id} was not found`
+    )
+  }
+
+  res.status(200).json({ reservation })
+}
+
+export const POST = async (
+  req: AuthenticatedMedusaRequest<AdminPostReservationsReservationReq>,
+  res: MedusaResponse
+) => {
+  const { id } = req.params
+  const { errors } = await updateReservationsWorkflow(req.scope).run({
+    input: {
+      updates: [{ ...req.validatedBody, id }],
+    },
+    throwOnError: false,
+  })
+
+  if (Array.isArray(errors) && errors[0]) {
+    throw errors[0].error
+  }
+
+  const remoteQuery = req.scope.resolve(ContainerRegistrationKeys.REMOTE_QUERY)
+
+  const queryObject = remoteQueryObjectFromString({
+    entryPoint: "reservation",
+    variables: {
+      filters: { id: req.params.id },
+    },
+    fields: req.remoteQueryConfig.fields,
+  })
+
+  const [reservation] = await remoteQuery(queryObject)
+
+  res.status(200).json({ reservation })
+}
+
+export const DELETE = async (
+  req: AuthenticatedMedusaRequest,
+  res: MedusaResponse
+) => {
+  const id = req.params.id
+
+  const { errors } = await deleteReservationsWorkflow(req.scope).run({
+    input: { ids: [id] },
+    throwOnError: false,
+  })
+
+  if (Array.isArray(errors) && errors[0]) {
+    throw errors[0].error
+  }
+
+  res.status(200).json({
+    id,
+    object: "reservation",
+    deleted: true,
+  })
+}

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

@@ -0,0 +1,62 @@
+import * as QueryConfig from "./query-config"
+
+import {
+  AdminGetReservationsParams,
+  AdminGetReservationsReservationParams,
+  AdminPostReservationsReq,
+  AdminPostReservationsReservationReq,
+} from "./validators"
+import { transformBody, transformQuery } from "../../../api/middlewares"
+
+import { MiddlewareRoute } from "../../../loaders/helpers/routing/types"
+import { authenticate } from "../../../utils/authenticate-middleware"
+
+export const adminReservationRoutesMiddlewares: MiddlewareRoute[] = [
+  {
+    method: ["ALL"],
+    matcher: "/admin/reservations*",
+    middlewares: [authenticate("admin", ["bearer", "session", "api-key"])],
+  },
+  {
+    method: ["GET"],
+    matcher: "/admin/reservations",
+    middlewares: [
+      transformQuery(
+        AdminGetReservationsParams,
+        QueryConfig.listTransformQueryConfig
+      ),
+    ],
+  },
+  {
+    method: ["GET"],
+    matcher: "/admin/reservations/:id",
+    middlewares: [
+      transformQuery(
+        AdminGetReservationsReservationParams,
+        QueryConfig.retrieveTransformQueryConfig
+      ),
+    ],
+  },
+  {
+    method: ["POST"],
+    matcher: "/admin/reservations",
+    middlewares: [
+      transformQuery(
+        AdminGetReservationsReservationParams,
+        QueryConfig.retrieveTransformQueryConfig
+      ),
+      transformBody(AdminPostReservationsReq),
+    ],
+  },
+  {
+    method: ["POST"],
+    matcher: "/admin/reservations/:id",
+    middlewares: [
+      transformQuery(
+        AdminGetReservationsReservationParams,
+        QueryConfig.retrieveTransformQueryConfig
+      ),
+      transformBody(AdminPostReservationsReservationReq),
+    ],
+  },
+]

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

@@ -0,0 +1,21 @@
+export const defaultAdminReservationFields = [
+  "id",
+  "location_id",
+  "inventory_item_id",
+  "quantity",
+  "line_item_id",
+  "description",
+  "metadata",
+  "created_at",
+  "updated_at",
+]
+
+export const retrieveTransformQueryConfig = {
+  defaults: defaultAdminReservationFields,
+  isList: false,
+}
+
+export const listTransformQueryConfig = {
+  ...retrieveTransformQueryConfig,
+  isList: true,
+}

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

@@ -0,0 +1,70 @@
+import {
+  AuthenticatedMedusaRequest,
+  MedusaResponse,
+} from "../../../types/routing"
+import {
+  ContainerRegistrationKeys,
+  remoteQueryObjectFromString,
+} from "@medusajs/utils"
+
+import { AdminPostReservationsReq } from "./validators"
+import { createReservationsWorkflow } from "@medusajs/core-flows"
+
+export const GET = async (
+  req: AuthenticatedMedusaRequest,
+  res: MedusaResponse
+) => {
+  const remoteQuery = req.scope.resolve(ContainerRegistrationKeys.REMOTE_QUERY)
+
+  const queryObject = remoteQueryObjectFromString({
+    entryPoint: "reservation",
+    variables: {
+      filters: req.filterableFields,
+      ...req.remoteQueryConfig.pagination,
+    },
+    fields: req.remoteQueryConfig.fields,
+  })
+
+  const { rows: reservations, metadata } = await remoteQuery(queryObject)
+
+  res.json({
+    reservations,
+    count: metadata.count,
+    offset: metadata.skip,
+    limit: metadata.take,
+  })
+}
+
+export const POST = async (
+  req: AuthenticatedMedusaRequest<AdminPostReservationsReq>,
+  res: MedusaResponse
+) => {
+  const input = [
+    {
+      ...req.validatedBody,
+    },
+  ]
+
+  const { result, errors } = await createReservationsWorkflow(req.scope).run({
+    input: { reservations: input },
+    throwOnError: false,
+  })
+
+  if (Array.isArray(errors) && errors[0]) {
+    throw errors[0].error
+  }
+
+  const remoteQuery = req.scope.resolve(ContainerRegistrationKeys.REMOTE_QUERY)
+
+  const queryObject = remoteQueryObjectFromString({
+    entryPoint: "reservation",
+    variables: {
+      filters: { id: result[0].id },
+    },
+    fields: req.remoteQueryConfig.fields,
+  })
+
+  const [reservation] = await remoteQuery(queryObject)
+
+  res.status(200).json({ reservation })
+}

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

@@ -0,0 +1,129 @@
+import { FindParams, extendedFindParamsMixin } from "../../../types/common"
+import {
+  IsArray,
+  IsBoolean,
+  IsNumber,
+  IsObject,
+  IsOptional,
+  IsString,
+  ValidateNested,
+} from "class-validator"
+
+import { IsType } from "../../../utils"
+import { OperatorMap } from "@medusajs/types"
+import { OperatorMapValidator } from "../../../types/validators/operator-map"
+import { Type } from "class-transformer"
+
+// TODO: naming
+export class AdminGetReservationsReservationParams extends FindParams {}
+
+/**
+ * Parameters used to filter and configure the pagination of the retrieved reservations.
+ */
+export class AdminGetReservationsParams extends extendedFindParamsMixin({
+  limit: 20,
+  offset: 0,
+}) {
+  /**
+   * Location IDs to filter reservations by.
+   */
+  @IsOptional()
+  @IsType([String, [String]])
+  location_id?: string | string[]
+
+  /**
+   * Inventory item IDs to filter reservations by.
+   */
+  @IsArray()
+  @IsString({ each: true })
+  @IsOptional()
+  inventory_item_id?: string[]
+
+  /**
+   * Line item IDs to filter reservations by.
+   */
+  @IsArray()
+  @IsString({ each: true })
+  @IsOptional()
+  line_item_id?: string[]
+
+  /**
+   * "Create by" user IDs to filter reservations by.
+   */
+  @IsArray()
+  @IsString({ each: true })
+  @IsOptional()
+  created_by?: string[]
+
+  /**
+   * Numerical filters to apply on the reservations' `quantity` field.
+   */
+  @IsOptional()
+  @ValidateNested()
+  @Type(() => OperatorMapValidator)
+  quantity?: OperatorMap<number>
+
+  /**
+   * Date filters to apply on the reservations' `created_at` field.
+   */
+  @IsOptional()
+  @ValidateNested()
+  @Type(() => OperatorMapValidator)
+  created_at?: OperatorMap<Date>
+
+  /**
+   * Date filters to apply on the reservations' `updated_at` field.
+   */
+  @IsOptional()
+  @ValidateNested()
+  @Type(() => OperatorMapValidator)
+  updated_at?: OperatorMap<Date>
+
+  /**
+   * String filters to apply on the reservations' `description` field.
+   */
+  @IsOptional()
+  @IsType([OperatorMapValidator, String])
+  description?: string | OperatorMap<string>
+}
+
+export class AdminPostReservationsReq {
+  @IsString()
+  @IsOptional()
+  line_item_id?: string
+
+  @IsString()
+  location_id: string
+
+  @IsString()
+  inventory_item_id: string
+
+  @IsNumber()
+  quantity: number
+
+  @IsString()
+  @IsOptional()
+  description?: string
+
+  @IsObject()
+  @IsOptional()
+  metadata?: Record<string, unknown>
+}
+
+export class AdminPostReservationsReservationReq {
+  @IsNumber()
+  @IsOptional()
+  quantity?: number
+
+  @IsString()
+  @IsOptional()
+  location_id?: string
+
+  @IsString()
+  @IsOptional()
+  description?: string
+
+  @IsObject()
+  @IsOptional()
+  metadata?: Record<string, unknown>
+}

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

@@ -13,10 +13,11 @@ import { adminPaymentRoutesMiddlewares } from "./admin/payments/middlewares"
 import { adminPriceListsRoutesMiddlewares } from "./admin/price-lists/middlewares"
 import { adminPricingRoutesMiddlewares } from "./admin/pricing/middlewares"
 import { adminProductCategoryRoutesMiddlewares } from "./admin/product-categories/middlewares"
-import { adminProductTypeRoutesMiddlewares } from "./admin/product-types/middlewares"
 import { adminProductRoutesMiddlewares } from "./admin/products/middlewares"
+import { adminProductTypeRoutesMiddlewares } from "./admin/product-types/middlewares"
 import { adminPromotionRoutesMiddlewares } from "./admin/promotions/middlewares"
 import { adminRegionRoutesMiddlewares } from "./admin/regions/middlewares"
+import { adminReservationRoutesMiddlewares } from "./admin/reservations/middlewares"
 import { adminSalesChannelRoutesMiddlewares } from "./admin/sales-channels/middlewares"
 import { adminShippingOptionRoutesMiddlewares } from "./admin/shipping-options/middlewares"
 import { adminShippingProfilesMiddlewares } from "./admin/shipping-profiles/middlewares"
@@ -70,6 +71,7 @@ export const config: MiddlewaresConfig = {
     ...adminUploadRoutesMiddlewares,
     ...adminFulfillmentSetsRoutesMiddlewares,
     ...adminProductCategoryRoutesMiddlewares,
+    ...adminReservationRoutesMiddlewares,
     ...adminShippingProfilesMiddlewares,
   ],
 }

packages/types/src/inventory/service-next.ts

@@ -1,4 +1,5 @@
 import { RestoreReturn, SoftDeleteReturn } from "../dal"
+
 import { Context } from "../shared-context"
 import { FindConfig } from "../common"
 import { IModuleService } from "../modules-sdk"
@@ -749,6 +750,47 @@ export interface IInventoryServiceNext extends IModuleService {
     context?: Context
   ): Promise<void>
 
+  /**
+   * This method soft deletes reservations by their IDs.
+   *
+   * @param {string[]} inventoryLevelIds - The reservations' IDs.
+   * @param {SoftDeleteReturn<TReturnableLinkableKeys>} config - An object that is used to specify an entity's related entities that should be soft-deleted when the main entity is soft-deleted.
+   * @param {Context} sharedContext - A context used to share resources, such as transaction manager, between the application and the module.
+   * @returns {Promise<void | Record<string, string[]>>} An object that includes the IDs of related records that were also soft deleted.
+   * If there are no related records, the promise resolves to `void`.
+   *
+   * @example
+   * await inventoryModuleService.softDeleteReservationItems([
+   *   "ilev_123",
+   * ])
+   */
+  softDeleteReservationItems<TReturnableLinkableKeys extends string = string>(
+    ReservationItemIds: string[],
+    config?: SoftDeleteReturn<TReturnableLinkableKeys>,
+    sharedContext?: Context
+  ): Promise<Record<string, string[]> | void>
+
+  /**
+   * This method restores soft deleted reservations by their IDs.
+   *
+   * @param {string[]} ReservationItemIds - The reservations' IDs.
+   * @param {RestoreReturn<TReturnableLinkableKeys>} config - Configurations determining which relations to restore along with each of the reservation. You can pass to its `returnLinkableKeys`
+   * property any of the reservation's relation attribute names, such as `{type relation name}`.
+   * @param {Context} sharedContext - A context used to share resources, such as transaction manager, between the application and the module.
+   * @returns {Promise<void | Record<string, string[]>>} An object that includes the IDs of related records that were restored.
+   * If there are no related records restored, the promise resolves to `void`.
+   *
+   * @example
+   * await inventoryModuleService.restoreReservationItems([
+   *   "ilev_123",
+   * ])
+   */
+  restoreReservationItems<TReturnableLinkableKeys extends string = string>(
+    ReservationItemIds: string[],
+    config?: RestoreReturn<TReturnableLinkableKeys>,
+    sharedContext?: Context
+  ): Promise<Record<string, string[]> | void>
+
   /**
    * This method deletes inventory items by their IDs.
    *

packages/types/src/workflow/index.ts

@@ -7,3 +7,4 @@ export * as UserWorkflow from "./user"
 export * as RegionWorkflow from "./region"
 export * as InviteWorkflow from "./invite"
 export * as FulfillmentWorkflow from "./fulfillment"
+export * as ReservationWorkflow from "./reservation"

packages/types/src/workflow/reservation/create-reservations.ts

@@ -0,0 +1,8 @@
+import { InventoryNext } from "../../inventory"
+
+export interface CreateReservationsWorkflowInput {
+  reservations: InventoryNext.CreateReservationItemInput[]
+}
+
+export type CreateReservationsWorkflowOutput =
+  InventoryNext.ReservationItemDTO[]

packages/types/src/workflow/reservation/index.ts

@@ -0,0 +1,2 @@
+export * from "./create-reservations"
+export * from "./update-reservations"

packages/types/src/workflow/reservation/update-reservations.ts

@@ -0,0 +1,8 @@
+import { InventoryNext } from "../../inventory"
+
+export interface UpdateReservationsWorkflowInput {
+  updates: InventoryNext.UpdateReservationItemInput[]
+}
+
+export type UpdateReservationsWorkflowOutput =
+  InventoryNext.ReservationItemDTO[]