feat(tax): add endpoints to create tax regions and tax rates (#6533)

**What**
Adds:
- POST /admin/tax-regions
- POST /admin/tax-rates
- GET /admin/tax-rates
- `createTaxRegionsWorkflow`
- `createTaxRatesWorkflow`

integration-tests/plugins/__tests__/tax/admin/tax.spec.ts

@@ -67,6 +67,8 @@ describe("Taxes - Admin", () => {
         name: "Test Rate",
         metadata: null,
         tax_region_id: region.id,
+        is_default: false,
+        is_combinable: false,
         created_at: expect.any(String),
         updated_at: expect.any(String),
         deleted_at: null,
@@ -74,4 +76,133 @@ describe("Taxes - Admin", () => {
       },
     })
   })
+
+  it("can create a tax region with rates and rules", async () => {
+    const api = useApi() as any
+    const regionRes = await api.post(
+      `/admin/tax-regions`,
+      {
+        country_code: "us",
+        default_tax_rate: {
+          code: "default",
+          rate: 2,
+          name: "default rate",
+        },
+      },
+      adminHeaders
+    )
+
+    const usRegionId = regionRes.data.tax_region.id
+
+    expect(regionRes.status).toEqual(200)
+    expect(regionRes.data).toEqual({
+      tax_region: {
+        id: expect.any(String),
+        country_code: "us",
+        parent_id: null,
+        province_code: null,
+        created_at: expect.any(String),
+        updated_at: expect.any(String),
+        deleted_at: null,
+        created_by: "admin_user",
+        provider_id: null,
+        metadata: null,
+      },
+    })
+
+    const rateRes = await api.post(
+      `/admin/tax-rates`,
+      {
+        tax_region_id: usRegionId,
+        code: "RATE2",
+        name: "another rate",
+        rate: 10,
+        rules: [{ reference: "product", reference_id: "prod_1234" }],
+      },
+      adminHeaders
+    )
+
+    expect(rateRes.status).toEqual(200)
+    expect(rateRes.data).toEqual({
+      tax_rate: {
+        id: expect.any(String),
+        code: "RATE2",
+        rate: 10,
+        name: "another rate",
+        is_default: false,
+        metadata: null,
+        tax_region_id: usRegionId,
+        created_at: expect.any(String),
+        updated_at: expect.any(String),
+        deleted_at: null,
+        created_by: "admin_user",
+        is_combinable: false,
+      },
+    })
+
+    const provRegRes = await api.post(
+      `/admin/tax-regions`,
+      {
+        country_code: "US",
+        parent_id: usRegionId,
+        province_code: "cA",
+      },
+      adminHeaders
+    )
+
+    expect(provRegRes.status).toEqual(200)
+    expect(provRegRes.data).toEqual({
+      tax_region: {
+        id: expect.any(String),
+        country_code: "us",
+        parent_id: usRegionId,
+        province_code: "ca",
+        created_at: expect.any(String),
+        updated_at: expect.any(String),
+        deleted_at: null,
+        created_by: "admin_user",
+        metadata: null,
+        provider_id: null,
+      },
+    })
+
+    const defRes = await api.post(
+      `/admin/tax-rates`,
+      {
+        tax_region_id: provRegRes.data.tax_region.id,
+        code: "DEFAULT",
+        name: "DEFAULT",
+        rate: 10,
+        is_default: true,
+      },
+      adminHeaders
+    )
+
+    const listRes = await api.get(`/admin/tax-rates`, adminHeaders)
+
+    expect(listRes.status).toEqual(200)
+    expect(listRes.data.tax_rates).toEqual(
+      expect.arrayContaining([
+        expect.objectContaining({
+          id: rateRes.data.tax_rate.id,
+          code: "RATE2",
+          rate: 10,
+          name: "another rate",
+          is_default: false,
+          metadata: null,
+          tax_region_id: usRegionId,
+          created_at: expect.any(String),
+          updated_at: expect.any(String),
+          deleted_at: null,
+          created_by: "admin_user",
+        }),
+        expect.objectContaining({ id: defRes.data.tax_rate.id }),
+        expect.objectContaining({
+          tax_region_id: usRegionId,
+          is_default: true,
+          rate: 2,
+        }),
+      ])
+    )
+  })
 })

packages/core-flows/src/index.ts

@@ -7,5 +7,6 @@ export * from "./invite"
 export * from "./promotion"
 export * from "./region"
 export * from "./user"
+export * from "./tax"
 export * from "./api-key"
 export * from "./store"

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

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

packages/core-flows/src/tax/steps/create-tax-rates.ts

@@ -0,0 +1,31 @@
+import { ModuleRegistrationName } from "@medusajs/modules-sdk"
+import { CreateTaxRateDTO, ITaxModuleService } from "@medusajs/types"
+import { StepResponse, createStep } from "@medusajs/workflows-sdk"
+
+export const createTaxRatesStepId = "create-tax-rates"
+export const createTaxRatesStep = createStep(
+  createTaxRatesStepId,
+  async (data: CreateTaxRateDTO[], { container }) => {
+    const service = container.resolve<ITaxModuleService>(
+      ModuleRegistrationName.TAX
+    )
+
+    const created = await service.create(data)
+
+    return new StepResponse(
+      created,
+      created.map((rate) => rate.id)
+    )
+  },
+  async (createdIds, { container }) => {
+    if (!createdIds?.length) {
+      return
+    }
+
+    const service = container.resolve<ITaxModuleService>(
+      ModuleRegistrationName.TAX
+    )
+
+    await service.delete(createdIds)
+  }
+)

packages/core-flows/src/tax/steps/create-tax-regions.ts

@@ -0,0 +1,31 @@
+import { ModuleRegistrationName } from "@medusajs/modules-sdk"
+import { CreateTaxRegionDTO, ITaxModuleService } from "@medusajs/types"
+import { StepResponse, createStep } from "@medusajs/workflows-sdk"
+
+export const createTaxRegionsStepId = "create-tax-regions"
+export const createTaxRegionsStep = createStep(
+  createTaxRegionsStepId,
+  async (data: CreateTaxRegionDTO[], { container }) => {
+    const service = container.resolve<ITaxModuleService>(
+      ModuleRegistrationName.TAX
+    )
+
+    const created = await service.createTaxRegions(data)
+
+    return new StepResponse(
+      created,
+      created.map((region) => region.id)
+    )
+  },
+  async (createdIds, { container }) => {
+    if (!createdIds?.length) {
+      return
+    }
+
+    const service = container.resolve<ITaxModuleService>(
+      ModuleRegistrationName.TAX
+    )
+
+    await service.delete(createdIds)
+  }
+)

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

@@ -0,0 +1,2 @@
+export * from "./create-tax-regions"
+export * from "./create-tax-rates"

packages/core-flows/src/tax/workflows/create-tax-rates.ts

@@ -0,0 +1,13 @@
+import { CreateTaxRateDTO, TaxRateDTO } from "@medusajs/types"
+import { WorkflowData, createWorkflow } from "@medusajs/workflows-sdk"
+import { createTaxRatesStep } from "../steps"
+
+type WorkflowInput = CreateTaxRateDTO[]
+
+export const createTaxRatesWorkflowId = "create-tax-rates"
+export const createTaxRatesWorkflow = createWorkflow(
+  createTaxRatesWorkflowId,
+  (input: WorkflowData<WorkflowInput>): WorkflowData<TaxRateDTO[]> => {
+    return createTaxRatesStep(input)
+  }
+)

packages/core-flows/src/tax/workflows/create-tax-regions.ts

@@ -0,0 +1,13 @@
+import { CreateTaxRegionDTO, TaxRegionDTO } from "@medusajs/types"
+import { WorkflowData, createWorkflow } from "@medusajs/workflows-sdk"
+import { createTaxRegionsStep } from "../steps"
+
+type WorkflowInput = CreateTaxRegionDTO[]
+
+export const createTaxRegionsWorkflowId = "create-tax-regions"
+export const createTaxRegionsWorkflow = createWorkflow(
+  createTaxRegionsWorkflowId,
+  (input: WorkflowData<WorkflowInput>): WorkflowData<TaxRegionDTO[]> => {
+    return createTaxRegionsStep(input)
+  }
+)

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

@@ -0,0 +1,2 @@
+export * from "./create-tax-regions"
+export * from "./create-tax-rates"

packages/medusa/src/api-v2/admin/tax-rates/middlewares.ts

@@ -1,19 +1,27 @@
 import * as QueryConfig from "./query-config"
 
-import { AdminGetTaxRatesTaxRateParams } from "./validators"
+import {
-import { transformQuery } from "../../../api/middlewares"
+  AdminGetTaxRatesTaxRateParams,
+  AdminPostTaxRatesReq,
+} from "./validators"
+import { transformBody, transformQuery } from "../../../api/middlewares"
 
 import { MiddlewareRoute } from "../../../loaders/helpers/routing/types"
 import { authenticate } from "../../../utils/authenticate-middleware"
 
 export const adminTaxRateRoutesMiddlewares: MiddlewareRoute[] = [
   {
-    method: ["ALL"],
+    method: "ALL",
     matcher: "/admin/tax-rates*",
     middlewares: [authenticate("admin", ["bearer", "session", "api-key"])],
   },
   {
-    method: ["GET"],
+    method: "POST",
+    matcher: "/admin/tax-rates",
+    middlewares: [transformBody(AdminPostTaxRatesReq)],
+  },
+  {
+    method: "GET",
     matcher: "/admin/tax-rates/:id",
     middlewares: [
       transformQuery(

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

@@ -6,6 +6,8 @@ export const defaultAdminTaxRateFields = [
   "code",
   "rate",
   "tax_region_id",
+  "is_default",
+  "is_combinable",
   "created_by",
   "created_at",
   "updated_at",

packages/medusa/src/api-v2/admin/tax-rates/route.ts

@@ -0,0 +1,58 @@
+import { createTaxRatesWorkflow } from "@medusajs/core-flows"
+import { remoteQueryObjectFromString } from "@medusajs/utils"
+import {
+  AuthenticatedMedusaRequest,
+  MedusaResponse,
+} from "../../../types/routing"
+import { defaultAdminTaxRateFields } from "./query-config"
+import { AdminPostTaxRatesReq } from "./validators"
+
+export const POST = async (
+  req: AuthenticatedMedusaRequest<AdminPostTaxRatesReq>,
+  res: MedusaResponse
+) => {
+  const { result, errors } = await createTaxRatesWorkflow(req.scope).run({
+    input: [
+      {
+        ...req.validatedBody,
+        created_by: req.auth.actor_id,
+      },
+    ],
+    throwOnError: false,
+  })
+
+  if (Array.isArray(errors) && errors[0]) {
+    throw errors[0].error
+  }
+
+  const remoteQuery = req.scope.resolve("remoteQuery")
+
+  const query = remoteQueryObjectFromString({
+    entryPoint: "tax_rate",
+    variables: { id: result[0].id },
+    fields: defaultAdminTaxRateFields,
+  })
+
+  const [taxRate] = await remoteQuery(query)
+
+  res.status(200).json({ tax_rate: taxRate })
+}
+
+export const GET = async (
+  req: AuthenticatedMedusaRequest,
+  res: MedusaResponse
+) => {
+  const remoteQuery = req.scope.resolve("remoteQuery")
+
+  const variables = { id: req.params.id }
+
+  const queryObject = remoteQueryObjectFromString({
+    entryPoint: "tax_rate",
+    variables,
+    fields: defaultAdminTaxRateFields,
+  })
+
+  const rates = await remoteQuery(queryObject)
+
+  res.status(200).json({ tax_rates: rates })
+}

packages/medusa/src/api-v2/admin/tax-rates/validators.ts

@@ -1,3 +1,54 @@
+// HEAD
+import { Type } from "class-transformer"
+import {
+  IsBoolean,
+  IsNumber,
+  IsObject,
+  IsOptional,
+  IsString,
+  ValidateNested,
+} from "class-validator"
 import { FindParams } from "../../../types/common"
 
 export class AdminGetTaxRatesTaxRateParams extends FindParams {}
+
+class CreateTaxRateRule {
+  @IsString()
+  reference: string
+
+  @IsString()
+  reference_id: string
+}
+
+export class AdminPostTaxRatesReq {
+  @IsOptional()
+  @IsNumber()
+  rate?: number | null
+
+  @IsOptional()
+  @IsString()
+  code?: string | null
+
+  @ValidateNested({ each: true })
+  @IsOptional()
+  @Type(() => CreateTaxRateRule)
+  rules?: CreateTaxRateRule[]
+
+  @IsString()
+  name: string
+
+  @IsBoolean()
+  @IsOptional()
+  is_default?: boolean
+
+  @IsBoolean()
+  @IsOptional()
+  is_combinable?: boolean
+
+  @IsString()
+  tax_region_id: string
+
+  @IsObject()
+  @IsOptional()
+  metadata?: Record<string, unknown>
+}

packages/medusa/src/api-v2/admin/tax-regions/middlewares.ts

@@ -0,0 +1,30 @@
+import * as QueryConfig from "./query-config"
+
+import { AdminGetTaxRegionsParams, AdminPostTaxRegionsReq } from "./validators"
+import { transformBody, transformQuery } from "../../../api/middlewares"
+
+import { MiddlewareRoute } from "../../../loaders/helpers/routing/types"
+import { authenticate } from "../../../utils/authenticate-middleware"
+
+export const adminTaxRegionRoutesMiddlewares: MiddlewareRoute[] = [
+  {
+    method: ["ALL"],
+    matcher: "/admin/tax-regions*",
+    middlewares: [authenticate("admin", ["bearer", "session", "api-key"])],
+  },
+  {
+    method: "POST",
+    matcher: "/admin/tax-regions",
+    middlewares: [transformBody(AdminPostTaxRegionsReq)],
+  },
+  {
+    method: "GET",
+    matcher: "/admin/tax-regions",
+    middlewares: [
+      transformQuery(
+        AdminGetTaxRegionsParams,
+        QueryConfig.listTransformQueryConfig
+      ),
+    ],
+  },
+]

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

@@ -0,0 +1,26 @@
+export const defaultAdminTaxRegionRelations = []
+export const allowedAdminTaxRegionRelations = []
+export const defaultAdminTaxRegionFields = [
+  "id",
+  "country_code",
+  "province_code",
+  "parent_id",
+  "provider_id",
+  "created_by",
+  "created_at",
+  "updated_at",
+  "deleted_at",
+  "metadata",
+]
+
+export const retrieveTransformQueryConfig = {
+  defaultFields: defaultAdminTaxRegionFields,
+  defaultRelations: defaultAdminTaxRegionRelations,
+  allowedRelations: allowedAdminTaxRegionRelations,
+  isList: false,
+}
+
+export const listTransformQueryConfig = {
+  defaultLimit: 20,
+  isList: true,
+}

packages/medusa/src/api-v2/admin/tax-regions/route.ts

@@ -0,0 +1,39 @@
+import { createTaxRegionsWorkflow } from "@medusajs/core-flows"
+import { remoteQueryObjectFromString } from "@medusajs/utils"
+import {
+  AuthenticatedMedusaRequest,
+  MedusaResponse,
+} from "../../../types/routing"
+import { defaultAdminTaxRegionFields } from "./query-config"
+import { AdminPostTaxRegionsReq } from "./validators"
+
+export const POST = async (
+  req: AuthenticatedMedusaRequest<AdminPostTaxRegionsReq>,
+  res: MedusaResponse
+) => {
+  const { result, errors } = await createTaxRegionsWorkflow(req.scope).run({
+    input: [
+      {
+        ...req.validatedBody,
+        created_by: req.auth.actor_id,
+      },
+    ],
+    throwOnError: false,
+  })
+
+  if (Array.isArray(errors) && errors[0]) {
+    throw errors[0].error
+  }
+
+  const remoteQuery = req.scope.resolve("remoteQuery")
+
+  const query = remoteQueryObjectFromString({
+    entryPoint: "tax_region",
+    variables: { id: result[0].id },
+    fields: defaultAdminTaxRegionFields,
+  })
+
+  const [taxRegion] = await remoteQuery(query)
+
+  res.status(200).json({ tax_region: taxRegion })
+}

packages/medusa/src/api-v2/admin/tax-regions/validators.ts

@@ -0,0 +1,127 @@
+import { OperatorMap } from "@medusajs/types"
+import { Type } from "class-transformer"
+import {
+  IsNumber,
+  IsObject,
+  IsOptional,
+  IsString,
+  ValidateNested,
+} from "class-validator"
+import { extendedFindParamsMixin, FindParams } from "../../../types/common"
+import { OperatorMapValidator } from "../../../types/validators/operator-map"
+
+export class AdminGetTaxRegionsTaxRegionParams extends FindParams {}
+
+export class AdminGetTaxRegionsParams extends extendedFindParamsMixin({
+  limit: 50,
+  offset: 0,
+}) {
+  /**
+   * Search parameter for regions.
+   */
+  @IsString({ each: true })
+  @IsOptional()
+  id?: string | string[]
+
+  /**
+   * Filter by country code.
+   */
+  @IsString({ each: true })
+  @IsOptional()
+  country_code?: string | string[]
+
+  /**
+   * Filter by province code
+   */
+  @IsString({ each: true })
+  @IsOptional()
+  province_code?: string | string[]
+
+  /**
+   * Filter by id of parent Tax Region.
+   */
+  @IsString({ each: true })
+  @IsOptional()
+  parent_id?: string | string[]
+
+  /**
+   * Filter by who created the Tax Region.
+   */
+  @IsString({ each: true })
+  @IsOptional()
+  created_by?: string | string[]
+
+  /**
+   * Date filters to apply on the Tax Regions' `created_at` date.
+   */
+  @IsOptional()
+  @ValidateNested()
+  @Type(() => OperatorMapValidator)
+  created_at?: OperatorMap<string>
+
+  /**
+   * Date filters to apply on the Tax Regions' `updated_at` date.
+   */
+  @IsOptional()
+  @ValidateNested()
+  @Type(() => OperatorMapValidator)
+  updated_at?: OperatorMap<string>
+
+  /**
+   * Date filters to apply on the Tax Regions' `deleted_at` date.
+   */
+  @ValidateNested()
+  @IsOptional()
+  @Type(() => OperatorMapValidator)
+  deleted_at?: OperatorMap<string>
+
+  // Additional filters from BaseFilterable
+  @IsOptional()
+  @ValidateNested({ each: true })
+  @Type(() => AdminGetTaxRegionsParams)
+  $and?: AdminGetTaxRegionsParams[]
+
+  @IsOptional()
+  @ValidateNested({ each: true })
+  @Type(() => AdminGetTaxRegionsParams)
+  $or?: AdminGetTaxRegionsParams[]
+}
+
+class CreateDefaultTaxRate {
+  @IsOptional()
+  @IsNumber()
+  rate?: number | null
+
+  @IsOptional()
+  @IsString()
+  code?: string | null
+
+  @IsString()
+  name: string
+
+  @IsObject()
+  @IsOptional()
+  metadata?: Record<string, unknown>
+}
+
+export class AdminPostTaxRegionsReq {
+  @IsString()
+  country_code: string
+
+  @IsString()
+  @IsOptional()
+  province_code?: string
+
+  @IsString()
+  @IsOptional()
+  parent_id?: string
+
+  @ValidateNested()
+  @IsOptional()
+  @Type(() => CreateDefaultTaxRate)
+  default_tax_rate?: CreateDefaultTaxRate
+
+  @IsObject()
+  @IsOptional()
+  metadata?: Record<string, unknown>
+}

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

@@ -6,6 +6,7 @@ import { adminCustomerRoutesMiddlewares } from "./admin/customers/middlewares"
 import { adminInviteRoutesMiddlewares } from "./admin/invites/middlewares"
 import { adminPromotionRoutesMiddlewares } from "./admin/promotions/middlewares"
 import { adminRegionRoutesMiddlewares } from "./admin/regions/middlewares"
+import { adminTaxRegionRoutesMiddlewares } from "./admin/tax-regions/middlewares"
 import { adminStoreRoutesMiddlewares } from "./admin/stores/middlewares"
 import { adminTaxRateRoutesMiddlewares } from "./admin/tax-rates/middlewares"
 import { adminUserRoutesMiddlewares } from "./admin/users/middlewares"
@@ -32,6 +33,7 @@ export const config: MiddlewaresConfig = {
     ...adminUserRoutesMiddlewares,
     ...adminInviteRoutesMiddlewares,
     ...adminTaxRateRoutesMiddlewares,
+    ...adminTaxRegionRoutesMiddlewares,
     ...adminApiKeyRoutesMiddlewares,
     ...hooksRoutesMiddlewares,
     ...adminStoreRoutesMiddlewares,

packages/tax/src/services/tax-module-service.ts

@@ -148,7 +148,7 @@ export default class TaxModuleService<
       await this.taxRateRuleService_.create(rulesToCreate, sharedContext)
     }
 
-    return await this.baseRepository_.serialize<TaxTypes.TaxRateDTO>(rates, {
+    return await this.baseRepository_.serialize<TaxTypes.TaxRateDTO[]>(rates, {
       populate: true,
     })
   }

packages/types/src/tax/common.ts

@@ -22,6 +22,18 @@ export interface TaxRateDTO {
    * Holds custom data in key-value pairs.
    */
   metadata: Record<string, unknown> | null
+  /**
+   * The id of the Tax Region the rate is associated with.
+   */
+  tax_region_id: string
+  /**
+   * Flag to indicate if the Tax Rate should be combined with parent rates.
+   */
+  is_combinable: boolean
+  /**
+   * Flag to indicate if the Tax Rate is the default rate for the region.
+   */
+  is_default: boolean
   /**
    * When the Tax Rate was created.
    */
@@ -30,6 +42,10 @@ export interface TaxRateDTO {
    * When the Tax Rate was updated.
    */
   updated_at: string | Date
+  /**
+   * When the Tax Rate was deleted.
+   */
+  deleted_at: Date | null
   /**
    * The ID of the user that created the Tax Rate.
    */