feat(core-flows,medusa,types,utils): add/remove fulfillment shipping option rules (#6698)

what:

- adds fulfillment shipping option rules batch endpoint
- remove fulfillment shipping option rules batch endpoint
- breaks my British based education to not call it fulfilment with a single "l"

.changeset/violet-deers-cross.md

@@ -0,0 +1,8 @@
+---
+"@medusajs/core-flows": patch
+"@medusajs/medusa": patch
+"@medusajs/types": patch
+"@medusajs/utils": patch
+---
+
+feat(core-flows,medusa,types,utils): add/remove fulfillment shipping option rules

integration-tests/modules/__tests__/fulfillment/admin/shipping-option-rules.spec.ts

@@ -0,0 +1,197 @@
+import { ModuleRegistrationName } from "@medusajs/modules-sdk"
+import { IFulfillmentModuleService } from "@medusajs/types"
+import { RuleOperator } from "@medusajs/utils"
+import { medusaIntegrationTestRunner } from "medusa-test-utils"
+import { createAdminUser } from "../../../../helpers/create-admin-user"
+
+jest.setTimeout(50000)
+
+const env = { MEDUSA_FF_MEDUSA_V2: true }
+const adminHeaders = { headers: { "x-medusa-access-token": "test_token" } }
+
+medusaIntegrationTestRunner({
+  env,
+  testSuite: ({ dbConnection, getContainer, api }) => {
+    describe("Admin: Shipping Option Rules API", () => {
+      let appContainer
+      let shippingOption
+      let fulfillmentModule: IFulfillmentModuleService
+      const shippingOptionRule = {
+        operator: RuleOperator.EQ,
+        attribute: "old_attr",
+        value: "old value",
+      }
+
+      beforeAll(async () => {
+        appContainer = getContainer()
+        fulfillmentModule = appContainer.resolve(
+          ModuleRegistrationName.FULFILLMENT
+        )
+      })
+
+      beforeEach(async () => {
+        await createAdminUser(dbConnection, adminHeaders, appContainer)
+
+        const shippingProfile = await fulfillmentModule.createShippingProfiles({
+          name: "Test",
+          type: "default",
+        })
+
+        const fulfillmentSet = await fulfillmentModule.create({
+          name: "Test",
+          type: "test-type",
+          service_zones: [
+            {
+              name: "Test",
+              geo_zones: [{ type: "country", country_code: "us" }],
+            },
+          ],
+        })
+
+        shippingOption = await fulfillmentModule.createShippingOptions({
+          name: "Test shipping option",
+          service_zone_id: fulfillmentSet.service_zones[0].id,
+          shipping_profile_id: shippingProfile.id,
+          provider_id: "manual_test-provider",
+          price_type: "flat",
+          type: {
+            label: "Test type",
+            description: "Test description",
+            code: "test-code",
+          },
+          rules: [shippingOptionRule],
+        })
+      })
+
+      describe("POST /admin/fulfillment/shipping-options/:id/rules/batch/add", () => {
+        it("should throw error when required params are missing", async () => {
+          const { response } = await api
+            .post(
+              `/admin/fulfillment/shipping-options/${shippingOption.id}/rules/batch/add`,
+              {
+                rules: [{ operator: RuleOperator.EQ, value: "new_value" }],
+              },
+              adminHeaders
+            )
+            .catch((e) => e)
+
+          expect(response.status).toEqual(400)
+          expect(response.data).toEqual({
+            type: "invalid_data",
+            message:
+              "attribute must be a string, attribute should not be empty",
+          })
+        })
+
+        it("should throw error when shipping option does not exist", async () => {
+          const { response } = await api
+            .post(
+              `/admin/fulfillment/shipping-options/does-not-exist/rules/batch/add`,
+              {
+                rules: [
+                  { attribute: "new_attr", operator: "eq", value: "new value" },
+                ],
+              },
+              adminHeaders
+            )
+            .catch((e) => e)
+
+          expect(response.status).toEqual(404)
+          expect(response.data).toEqual({
+            type: "not_found",
+            message:
+              "Shipping_option with shipping_option_id does-not-exist does not exist.",
+          })
+        })
+
+        it("should add rules to a shipping option successfully", async () => {
+          const response = await api.post(
+            `/admin/fulfillment/shipping-options/${shippingOption.id}/rules/batch/add`,
+            {
+              rules: [
+                { operator: "eq", attribute: "new_attr", value: "new value" },
+              ],
+            },
+            adminHeaders
+          )
+
+          expect(response.status).toEqual(200)
+          expect(response.data.shipping_option).toEqual(
+            expect.objectContaining({
+              id: shippingOption.id,
+              rules: expect.arrayContaining([
+                expect.objectContaining({
+                  id: expect.any(String),
+                  operator: "eq",
+                  attribute: "old_attr",
+                  value: "old value",
+                  shipping_option_id: shippingOption.id,
+                }),
+                expect.objectContaining({
+                  id: expect.any(String),
+                  operator: "eq",
+                  attribute: "new_attr",
+                  value: "new value",
+                  shipping_option_id: shippingOption.id,
+                }),
+              ]),
+            })
+          )
+        })
+      })
+
+      describe("POST /admin/fulfillment/shipping-options/:id/rules/batch/remove", () => {
+        it("should throw error when required params are missing", async () => {
+          const { response } = await api
+            .post(
+              `/admin/fulfillment/shipping-options/${shippingOption.id}/rules/batch/remove`,
+              {},
+              adminHeaders
+            )
+            .catch((e) => e)
+
+          expect(response.status).toEqual(400)
+          expect(response.data).toEqual({
+            type: "invalid_data",
+            message:
+              "each value in rule_ids must be a string, rule_ids should not be empty",
+          })
+        })
+
+        it("should throw error when shipping option does not exist", async () => {
+          const { response } = await api
+            .post(
+              `/admin/fulfillment/shipping-options/does-not-exist/rules/batch/remove`,
+              { rule_ids: ["test"] },
+              adminHeaders
+            )
+            .catch((e) => e)
+
+          expect(response.status).toEqual(404)
+          expect(response.data).toEqual({
+            type: "not_found",
+            message: "ShippingOption with id: does-not-exist was not found",
+          })
+        })
+
+        it("should add rules to a shipping option successfully", async () => {
+          const response = await api.post(
+            `/admin/fulfillment/shipping-options/${shippingOption.id}/rules/batch/remove`,
+            {
+              rule_ids: [shippingOption.rules[0].id],
+            },
+            adminHeaders
+          )
+
+          expect(response.status).toEqual(200)
+          expect(response.data.shipping_option).toEqual(
+            expect.objectContaining({
+              id: shippingOption.id,
+              rules: [],
+            })
+          )
+        })
+      })
+    })
+  },
+})

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

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

packages/core-flows/src/fulfillment/steps/add-rules-to-fulfillment-shipping-option.ts

@@ -0,0 +1,41 @@
+import { ModuleRegistrationName } from "@medusajs/modules-sdk"
+import {
+  AddFulfillmentShippingOptionRulesWorkflowDTO,
+  IFulfillmentModuleService,
+} from "@medusajs/types"
+import { StepResponse, createStep } from "@medusajs/workflows-sdk"
+
+export const addRulesToFulfillmentShippingOptionStepId =
+  "add-rules-to-fulfillment-shipping-option"
+export const addRulesToFulfillmentShippingOptionStep = createStep(
+  addRulesToFulfillmentShippingOptionStepId,
+  async (
+    input: AddFulfillmentShippingOptionRulesWorkflowDTO,
+    { container }
+  ) => {
+    const { data } = input
+
+    const fulfillmentModule = container.resolve<IFulfillmentModuleService>(
+      ModuleRegistrationName.FULFILLMENT
+    )
+
+    const createdPromotionRules =
+      await fulfillmentModule.createShippingOptionRules(data)
+
+    return new StepResponse(
+      createdPromotionRules,
+      createdPromotionRules.map((pr) => pr.id)
+    )
+  },
+  async (ruleIds, { container }) => {
+    if (!ruleIds?.length) {
+      return
+    }
+
+    const fulfillmentModule = container.resolve<IFulfillmentModuleService>(
+      ModuleRegistrationName.FULFILLMENT
+    )
+
+    await fulfillmentModule.deleteShippingOptionRules(ruleIds)
+  }
+)

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

@@ -0,0 +1,2 @@
+export * from "./add-rules-to-fulfillment-shipping-option"
+export * from "./remove-rules-from-fulfillment-shipping-option"

packages/core-flows/src/fulfillment/steps/remove-rules-from-fulfillment-shipping-option.ts

@@ -0,0 +1,50 @@
+import { ModuleRegistrationName } from "@medusajs/modules-sdk"
+import {
+  IFulfillmentModuleService,
+  RemoveFulfillmentShippingOptionRulesWorkflowDTO,
+  ShippingOptionRuleOperatorType,
+} from "@medusajs/types"
+import { StepResponse, createStep } from "@medusajs/workflows-sdk"
+
+export const removeRulesFromFulfillmentShippingOptionStepId =
+  "remove-rules-from-fulfillment-shipping-option"
+export const removeRulesFromFulfillmentShippingOptionStep = createStep(
+  removeRulesFromFulfillmentShippingOptionStepId,
+  async (
+    input: RemoveFulfillmentShippingOptionRulesWorkflowDTO,
+    { container }
+  ) => {
+    const { ids } = input
+
+    const fulfillmentModule = container.resolve<IFulfillmentModuleService>(
+      ModuleRegistrationName.FULFILLMENT
+    )
+
+    const shippingOptionRules = await fulfillmentModule.listShippingOptionRules(
+      { id: ids },
+      { select: ["attribute", "operator", "value", "shipping_option_id"] }
+    )
+
+    await fulfillmentModule.deleteShippingOptionRules(ids)
+
+    return new StepResponse(null, shippingOptionRules)
+  },
+  async (shippingOptionRules, { container }) => {
+    if (!shippingOptionRules?.length) {
+      return
+    }
+
+    const fulfillmentModule = container.resolve<IFulfillmentModuleService>(
+      ModuleRegistrationName.FULFILLMENT
+    )
+
+    await fulfillmentModule.createShippingOptionRules(
+      shippingOptionRules.map((rule) => ({
+        attribute: rule.attribute,
+        operator: rule.operator as ShippingOptionRuleOperatorType,
+        value: rule.value as unknown as string | string[],
+        shipping_option_id: rule.shipping_option_id,
+      }))
+    )
+  }
+)

packages/core-flows/src/fulfillment/workflows/add-rules-to-fulfillment-shipping-option.ts

@@ -0,0 +1,14 @@
+import { AddFulfillmentShippingOptionRulesWorkflowDTO } from "@medusajs/types"
+import { WorkflowData, createWorkflow } from "@medusajs/workflows-sdk"
+import { addRulesToFulfillmentShippingOptionStep } from "../steps"
+
+export const addRulesToFulfillmentShippingOptionWorkflowId =
+  "add-rules-to-fulfillment-shipping-option-workflow"
+export const addRulesToFulfillmentShippingOptionWorkflow = createWorkflow(
+  addRulesToFulfillmentShippingOptionWorkflowId,
+  (
+    input: WorkflowData<AddFulfillmentShippingOptionRulesWorkflowDTO>
+  ): WorkflowData<void> => {
+    addRulesToFulfillmentShippingOptionStep(input)
+  }
+)

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

@@ -0,0 +1,2 @@
+export * from "./add-rules-to-fulfillment-shipping-option"
+export * from "./remove-rules-from-fulfillment-shipping-option"

packages/core-flows/src/fulfillment/workflows/remove-rules-from-fulfillment-shipping-option.ts

@@ -0,0 +1,14 @@
+import { RemoveFulfillmentShippingOptionRulesWorkflowDTO } from "@medusajs/types"
+import { WorkflowData, createWorkflow } from "@medusajs/workflows-sdk"
+import { removeRulesFromFulfillmentShippingOptionStep } from "../steps"
+
+export const removeRulesFromFulfillmentShippingOptionWorkflowId =
+  "remove-rules-from-fulfillment-shipping-option-workflow"
+export const removeRulesFromFulfillmentShippingOptionWorkflow = createWorkflow(
+  removeRulesFromFulfillmentShippingOptionWorkflowId,
+  (
+    input: WorkflowData<RemoveFulfillmentShippingOptionRulesWorkflowDTO>
+  ): WorkflowData<void> => {
+    removeRulesFromFulfillmentShippingOptionStep(input)
+  }
+)

packages/core-flows/src/index.ts

@@ -4,6 +4,7 @@ export * from "./customer"
 export * from "./customer-group"
 export * from "./definition"
 export * from "./definitions"
+export * from "./fulfillment"
 export * as Handlers from "./handlers"
 export * from "./invite"
 export * from "./payment"

packages/fulfillment/src/models/shipping-option-rule.ts

@@ -1,10 +1,10 @@
+import { DAL } from "@medusajs/types"
 import {
   createPsqlIndexStatementHelper,
   DALUtils,
   generateEntityId,
+  RuleOperator,
 } from "@medusajs/utils"
-
-import { DAL } from "@medusajs/types"
 import {
   BeforeCreate,
   Entity,
@@ -17,7 +17,6 @@ import {
   Property,
 } from "@mikro-orm/core"
 import ShippingOption from "./shipping-option"
-import { RuleOperator } from "@utils"
 
 type ShippingOptionRuleOptionalProps = DAL.SoftDeletableEntityDateColumns
 

packages/fulfillment/src/utils/__tests__/utils.spec.ts

@@ -1,4 +1,5 @@
-import { isContextValid, RuleOperator } from "../utils"
+import { RuleOperator } from "@medusajs/utils"
+import { isContextValid } from "../utils"
 
 describe("isContextValidForRules", () => {
   const context = {

packages/fulfillment/src/utils/utils.ts

@@ -1,4 +1,9 @@
-import { isString, MedusaError, pickValueFromObject } from "@medusajs/utils"
+import {
+  isString,
+  MedusaError,
+  pickValueFromObject,
+  RuleOperator,
+} from "@medusajs/utils"
 
 /**
  * The rule engine here is kept inside the module as of now, but it could be moved
@@ -14,17 +19,6 @@ export type Rule = {
   value: string | string[] | null
 }
 
-export enum RuleOperator {
-  IN = "in",
-  EQ = "eq",
-  NE = "ne",
-  GT = "gt",
-  GTE = "gte",
-  LT = "lt",
-  LTE = "lte",
-  NIN = "nin",
-}
-
 export const availableOperators = Object.values(RuleOperator)
 
 const isDate = (str: string) => {

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

@@ -0,0 +1,29 @@
+import { transformBody } from "../../../api/middlewares"
+import { MiddlewareRoute } from "../../../loaders/helpers/routing/types"
+import { authenticate } from "../../../utils/authenticate-middleware"
+import {
+  AdminPostFulfillmentShippingOptionsRulesBatchAddReq,
+  AdminPostFulfillmentShippingOptionsRulesBatchRemoveReq,
+} from "./validators"
+
+export const adminFulfillmentRoutesMiddlewares: MiddlewareRoute[] = [
+  {
+    matcher: "/admin/fulfillment*",
+    middlewares: [authenticate("admin", ["bearer", "session"])],
+  },
+  {
+    method: ["POST"],
+    matcher: "/admin/fulfillment/shipping-options/:id/rules/batch/add",
+    middlewares: [
+      transformBody(AdminPostFulfillmentShippingOptionsRulesBatchAddReq),
+    ],
+  },
+
+  {
+    method: ["POST"],
+    matcher: "/admin/fulfillment/shipping-options/:id/rules/batch/remove",
+    middlewares: [
+      transformBody(AdminPostFulfillmentShippingOptionsRulesBatchRemoveReq),
+    ],
+  },
+]

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

@@ -0,0 +1,29 @@
+export const defaultAdminShippingOptionRelations = ["rules"]
+export const allowedAdminShippingOptionRelations = [
+  ...defaultAdminShippingOptionRelations,
+]
+export const defaultAdminShippingOptionFields = [
+  "id",
+  "name",
+  "price_type",
+  "data",
+  "metadata",
+  "created_at",
+  "updated_at",
+  "rules.id",
+  "rules.attribute",
+  "rules.operator",
+  "rules.value",
+]
+
+export const retrieveTransformQueryConfig = {
+  defaultFields: defaultAdminShippingOptionFields,
+  defaultRelations: defaultAdminShippingOptionRelations,
+  allowedRelations: allowedAdminShippingOptionRelations,
+  isList: false,
+}
+
+export const listTransformQueryConfig = {
+  ...retrieveTransformQueryConfig,
+  isList: true,
+}

packages/medusa/src/api-v2/admin/fulfillment/shipping-options/[id]/rules/batch/add/route.ts

@@ -0,0 +1,45 @@
+import { addRulesToFulfillmentShippingOptionWorkflow } from "@medusajs/core-flows"
+import { ModuleRegistrationName } from "@medusajs/modules-sdk"
+import { IFulfillmentModuleService } from "@medusajs/types"
+import {
+  AuthenticatedMedusaRequest,
+  MedusaResponse,
+} from "../../../../../../../../types/routing"
+import {
+  defaultAdminShippingOptionFields,
+  defaultAdminShippingOptionRelations,
+} from "../../../../../query-config"
+import { AdminPostFulfillmentShippingOptionsRulesBatchAddReq } from "../../../../../validators"
+
+export const POST = async (
+  req: AuthenticatedMedusaRequest<AdminPostFulfillmentShippingOptionsRulesBatchAddReq>,
+  res: MedusaResponse
+) => {
+  const id = req.params.id
+  const workflow = addRulesToFulfillmentShippingOptionWorkflow(req.scope)
+
+  const { errors } = await workflow.run({
+    input: {
+      data: req.validatedBody.rules.map((rule) => ({
+        ...rule,
+        shipping_option_id: id,
+      })),
+    },
+    throwOnError: false,
+  })
+
+  if (Array.isArray(errors) && errors[0]) {
+    throw errors[0].error
+  }
+
+  const fulfillmentService: IFulfillmentModuleService = req.scope.resolve(
+    ModuleRegistrationName.FULFILLMENT
+  )
+
+  const shippingOption = await fulfillmentService.retrieveShippingOption(id, {
+    select: defaultAdminShippingOptionFields,
+    relations: defaultAdminShippingOptionRelations,
+  })
+
+  res.status(200).json({ shipping_option: shippingOption })
+}

packages/medusa/src/api-v2/admin/fulfillment/shipping-options/[id]/rules/batch/remove/route.ts

@@ -0,0 +1,40 @@
+import { removeRulesFromFulfillmentShippingOptionWorkflow } from "@medusajs/core-flows"
+import { ModuleRegistrationName } from "@medusajs/modules-sdk"
+import { IFulfillmentModuleService } from "@medusajs/types"
+import {
+  AuthenticatedMedusaRequest,
+  MedusaResponse,
+} from "../../../../../../../../types/routing"
+import {
+  defaultAdminShippingOptionFields,
+  defaultAdminShippingOptionRelations,
+} from "../../../../../query-config"
+import { AdminPostFulfillmentShippingOptionsRulesBatchRemoveReq } from "../../../../../validators"
+
+export const POST = async (
+  req: AuthenticatedMedusaRequest<AdminPostFulfillmentShippingOptionsRulesBatchRemoveReq>,
+  res: MedusaResponse
+) => {
+  const id = req.params.id
+  const workflow = removeRulesFromFulfillmentShippingOptionWorkflow(req.scope)
+
+  const { errors } = await workflow.run({
+    input: { ids: req.validatedBody.rule_ids },
+    throwOnError: false,
+  })
+
+  if (Array.isArray(errors) && errors[0]) {
+    throw errors[0].error
+  }
+
+  const fulfillmentService: IFulfillmentModuleService = req.scope.resolve(
+    ModuleRegistrationName.FULFILLMENT
+  )
+
+  const shippingOption = await fulfillmentService.retrieveShippingOption(id, {
+    select: defaultAdminShippingOptionFields,
+    relations: defaultAdminShippingOptionRelations,
+  })
+
+  res.status(200).json({ shipping_option: shippingOption })
+}

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

@@ -0,0 +1,36 @@
+import { RuleOperator } from "@medusajs/utils"
+import { Type } from "class-transformer"
+import {
+  ArrayNotEmpty,
+  IsArray,
+  IsEnum,
+  IsNotEmpty,
+  IsString,
+  ValidateNested,
+} from "class-validator"
+import { IsType } from "../../../utils"
+
+export class AdminPostFulfillmentShippingOptionsRulesBatchAddReq {
+  @IsArray()
+  @ValidateNested({ each: true })
+  @Type(() => FulfillmentRuleCreate)
+  rules: FulfillmentRuleCreate[]
+}
+
+export class AdminPostFulfillmentShippingOptionsRulesBatchRemoveReq {
+  @ArrayNotEmpty()
+  @IsString({ each: true })
+  rule_ids: string[]
+}
+
+export class FulfillmentRuleCreate {
+  @IsEnum(RuleOperator)
+  operator: RuleOperator
+
+  @IsNotEmpty()
+  @IsString()
+  attribute: string
+
+  @IsType([String, [String]])
+  value: string | string[]
+}

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

@@ -5,6 +5,7 @@ import { adminCollectionRoutesMiddlewares } from "./admin/collections/middleware
 import { adminCurrencyRoutesMiddlewares } from "./admin/currencies/middlewares"
 import { adminCustomerGroupRoutesMiddlewares } from "./admin/customer-groups/middlewares"
 import { adminCustomerRoutesMiddlewares } from "./admin/customers/middlewares"
+import { adminFulfillmentRoutesMiddlewares } from "./admin/fulfillment/middlewares"
 import { adminInventoryRoutesMiddlewares } from "./admin/inventory-items/middlewares"
 import { adminInviteRoutesMiddlewares } from "./admin/invites/middlewares"
 import { adminPaymentRoutesMiddlewares } from "./admin/payments/middlewares"
@@ -53,5 +54,6 @@ export const config: MiddlewaresConfig = {
     ...adminInventoryRoutesMiddlewares,
     ...adminCollectionRoutesMiddlewares,
     ...adminPricingRoutesMiddlewares,
+    ...adminFulfillmentRoutesMiddlewares,
   ],
 }

packages/types/src/fulfillment/index.ts

@@ -1,4 +1,5 @@
 export * from "./common"
 export * from "./mutations"
-export * from "./service"
 export * from "./provider"
+export * from "./service"
+export * from "./workflows"

packages/types/src/fulfillment/mutations/shipping-option-rule.ts

@@ -1,6 +1,16 @@
+export type ShippingOptionRuleOperatorType =
+  | "in"
+  | "eq"
+  | "ne"
+  | "gt"
+  | "gte"
+  | "lt"
+  | "lte"
+  | "nin"
+
 export interface CreateShippingOptionRuleDTO {
   attribute: string
-  operator: "in" | "eq" | "ne" | "gt" | "gte" | "lt" | "lte" | "nin"
+  operator: ShippingOptionRuleOperatorType
   value: string | string[]
   shipping_option_id: string
 }

packages/types/src/fulfillment/workflows.ts

@@ -0,0 +1,9 @@
+import { CreateShippingOptionRuleDTO } from "./mutations"
+
+export type AddFulfillmentShippingOptionRulesWorkflowDTO = {
+  data: CreateShippingOptionRuleDTO[]
+}
+
+export type RemoveFulfillmentShippingOptionRulesWorkflowDTO = {
+  ids: string[]
+}

packages/utils/src/common/index.ts

@@ -7,8 +7,8 @@ export * from "./convert-item-response-to-update-request"
 export * from "./create-container-like"
 export * from "./create-psql-index-helper"
 export * from "./deduplicate"
-export * from "./deep-equal-obj"
 export * from "./deep-copy"
+export * from "./deep-equal-obj"
 export * from "./errors"
 export * from "./generate-entity-id"
 export * from "./generate-linkable-keys-map"
@@ -42,6 +42,7 @@ export * from "./remote-query-object-from-string"
 export * from "./remote-query-object-to-string"
 export * from "./remove-nullisih"
 export * from "./remove-undefined"
+export * from "./rules"
 export * from "./selector-constraints-to-string"
 export * from "./set-metadata"
 export * from "./simple-hash"

packages/utils/src/common/rules.ts

@@ -0,0 +1,10 @@
+export enum RuleOperator {
+  IN = "in",
+  EQ = "eq",
+  NE = "ne",
+  GT = "gt",
+  GTE = "gte",
+  LT = "lt",
+  LTE = "lte",
+  NIN = "nin",
+}