feat(dashboard, js-sdk, medusa, tax, types): custom tax providers (#12297)

* wip: setup loaders, add endpoints, module work, types, js sdk

* fix: tax module provider loader

* feat: select provider on region create, fix enpoint middleware registration

* feat: edit form

* fix: rename param

* chore: changeset

* fix: don't default to system provider

* fix: admin fixes, dispalt tax provider

* fix: some tests and types

* fix: remove provider from province regions in test

* fix: more tests, optional provider for sublevel regions, fix few types

* fix: OE test

* feat: edit tax region admin, update tax region core flow changes

* feat: migrate script

* fix: refactor

* chore: use query graph

* feat: provider section

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

@@ -17,7 +17,7 @@ export type UpdateTaxRegionsStepInput = UpdateTaxRegionDTO[]
 export const updateTaxRegionsStepId = "update-tax-regions"
 /**
  * This step updates tax regions.
- * 
+ *
  * @example
  * const data = updateTaxRegionsStep([
  *   {
@@ -45,6 +45,7 @@ export const updateTaxRegionsStep = createStep(
         id: d.id,
         province_code: d.province_code,
         metadata: d.metadata,
+        provider_id: d.provider_id,
       }))
     )
 

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

@@ -20,10 +20,10 @@ export const updateTaxRegionsWorkflowId = "update-tax-regions"
 /**
  * This workflow updates one or more tax regions. It's used by the
  * [Update Tax Regions Admin API Route](https://docs.medusajs.com/api/admin#tax-regions_posttaxregionsid).
- * 
+ *
  * You can use this workflow within your own customizations or custom workflows, allowing you
  * to update tax regions in your custom flows.
- * 
+ *
  * @example
  * const { result } = await updateTaxRegionsWorkflow(container)
  * .run({
@@ -34,9 +34,9 @@ export const updateTaxRegionsWorkflowId = "update-tax-regions"
  *     }
  *   ]
  * })
- * 
+ *
  * @summary
- * 
+ *
  * Update one or more tax regions.
  */
 export const updateTaxRegionsWorkflow = createWorkflow(

packages/core/js-sdk/src/admin/index.ts

@@ -37,6 +37,7 @@ import { ShippingOption } from "./shipping-option"
 import { ShippingProfile } from "./shipping-profile"
 import { StockLocation } from "./stock-location"
 import { Store } from "./store"
+import { TaxProvider } from "./tax-provider"
 import { TaxRate } from "./tax-rate"
 import { TaxRegion } from "./tax-region"
 import { Upload } from "./upload"
@@ -208,6 +209,10 @@ export class Admin {
    * @tags promotion
    */
   public promotion: Promotion
+  /**
+   * @tags tax
+   */
+  public taxProvider: TaxProvider
   /**
    * @tags promotion
    */
@@ -261,5 +266,6 @@ export class Admin {
     this.promotion = new Promotion(client)
     this.campaign = new Campaign(client)
     this.plugin = new Plugin(client)
+    this.taxProvider = new TaxProvider(client)
   }
 }

packages/core/js-sdk/src/admin/tax-provider.ts

@@ -0,0 +1,51 @@
+import { HttpTypes } from "@medusajs/types"
+import { Client } from "../client"
+import { ClientHeaders } from "../types"
+
+const taxProviderUrl = "/admin/tax-providers"
+
+export class TaxProvider {
+  /**
+   * @ignore
+   */
+  private client: Client
+  /**
+   * @ignore
+   */
+  constructor(client: Client) {
+    this.client = client
+  }
+
+  /**
+   * This method retrieves a list of tax providers. It sends a request to the
+   * [List Tax Providers](https://docs.medusajs.com/api/admin#tax-providers_gettaxproviders)
+   * API route.
+   *
+   * @param query - Filters and pagination configurations.
+   * @param headers - Headers to pass in the request.
+   * @returns The list of tax providers.
+   *
+   * @example
+   * To retrieve the list of tax providers:
+   *
+   * ```ts
+   * sdk.admin.taxProvider.list()
+   * .then(({ tax_providers, count, limit, offset }) => {
+   *   console.log(tax_providers)
+   * })
+   * ```
+   */
+  async list(
+    query?: HttpTypes.AdminGetTaxProvidersParams,
+    headers?: ClientHeaders
+  ) {
+    return await this.client.fetch<HttpTypes.AdminTaxProviderListResponse>(
+      taxProviderUrl,
+      {
+        method: "GET",
+        headers,
+        query,
+      }
+    )
+  }
+}

packages/core/js-sdk/src/admin/tax-rate.ts

@@ -20,12 +20,12 @@ export class TaxRate {
    * This method creates a tax rate. It sends a request to the
    * [Create Tax Rate](https://docs.medusajs.com/api/admin#tax-rates_posttaxrates)
    * API route.
-   * 
+   *
    * @param body - The details of the tax rate to create.
    * @param query - Configure the fields and relations to retrieve in the tax rate.
    * @param headers - Headers to pass in the request.
    * @returns The tax rate's details.
-   * 
+   *
    * @example
    * sdk.admin.taxRate.create({
    *   name: "VAT",
@@ -54,13 +54,13 @@ export class TaxRate {
    * This method updates a tax rate. It sends a request to the
    * [Update Tax Rate](https://docs.medusajs.com/api/admin#tax-rates_posttaxratesid)
    * API route.
-   * 
+   *
    * @param id - The ID of the tax rate to update.
    * @param body - The details of the tax rate to update.
    * @param query - Configure the fields and relations to retrieve in the tax rate.
    * @param headers - Headers to pass in the request.
    * @returns The tax rate's details.
-   * 
+   *
    * @example
    * sdk.admin.taxRate.update("txrat_123", {
    *   name: "VAT",
@@ -91,11 +91,11 @@ export class TaxRate {
    * This method deletes a tax rate. It sends a request to the
    * [Delete Tax Rate](https://docs.medusajs.com/api/admin#tax-rates_deletetaxratesid)
    * API route.
-   * 
+   *
    * @param id - The ID of the tax rate to delete.
    * @param headers - Headers to pass in the request.
    * @returns The deletion's details.
-   * 
+   *
    * @example
    * sdk.admin.taxRate.delete("txrat_123")
    * .then(({ deleted }) => {
@@ -116,24 +116,24 @@ export class TaxRate {
    * This method retrieves a tax rate. It sends a request to the
    * [Get Tax Rate](https://docs.medusajs.com/api/admin#tax-rates_gettaxratesid)
    * API route.
-   * 
+   *
    * @param id - The ID of the tax rate to retrieve.
    * @param query - Configure the fields and relations to retrieve in the tax rate.
    * @param headers - Headers to pass in the request.
    * @returns The tax rate's details.
-   * 
+   *
    * @example
    * To retrieve a tax rate by its ID:
-   * 
+   *
    * ```ts
    * sdk.admin.taxRate.retrieve("txrat_123")
    * .then(({ tax_rate }) => {
    *   console.log(tax_rate)
    * })
    * ```
-   * 
+   *
    * To specify the fields and relations to retrieve:
-   * 
+   *
    * ```ts
    * sdk.admin.taxRate.retrieve("txrat_123", {
    *   fields: "id,*tax_region"
@@ -142,7 +142,7 @@ export class TaxRate {
    *   console.log(tax_rate)
    * })
    * ```
-   * 
+   *
    * Learn more about the `fields` property in the [API reference](https://docs.medusajs.com/api/admin#select-fields-and-relations).
    */
   async retrieve(
@@ -164,25 +164,25 @@ export class TaxRate {
    * This method retrieves a list of tax rates. It sends a request to the
    * [List Tax Rates](https://docs.medusajs.com/api/admin#tax-rates_gettaxrates)
    * API route.
-   * 
+   *
    * @param query - Filters and pagination configurations.
    * @param headers - Headers to pass in the request.
    * @returns The list of tax rates.
-   * 
+   *
    * @example
    * To retrieve the list of tax rates:
-   * 
+   *
    * ```ts
    * sdk.admin.taxRate.list()
    * .then(({ tax_rates, count, limit, offset }) => {
    *   console.log(tax_rates)
    * })
    * ```
-   * 
+   *
    * To configure the pagination, pass the `limit` and `offset` query parameters.
-   * 
+   *
    * For example, to retrieve only 10 items and skip 10 items:
-   * 
+   *
    * ```ts
    * sdk.admin.taxRate.list({
    *   limit: 10,
@@ -192,10 +192,10 @@ export class TaxRate {
    *   console.log(tax_rates)
    * })
    * ```
-   * 
+   *
    * Using the `fields` query parameter, you can specify the fields and relations to retrieve
    * in each tax rate:
-   * 
+   *
    * ```ts
    * sdk.admin.taxRate.list({
    *   fields: "id,*tax_region"
@@ -204,7 +204,7 @@ export class TaxRate {
    *   console.log(tax_rates)
    * })
    * ```
-   * 
+   *
    * Learn more about the `fields` property in the [API reference](https://docs.medusajs.com/api/admin#select-fields-and-relations).
    */
   async list(

packages/core/js-sdk/src/admin/tax-region.ts

@@ -6,7 +6,7 @@ const taxRegionUrl = "/admin/tax-regions"
 
 /**
  * @privateRemarks
- * 
+ *
  * TODO: Add support for updating a tax region
  */
 export class TaxRegion {
@@ -25,12 +25,12 @@ export class TaxRegion {
    * This method creates a tax region. It sends a request to the
    * [Create Tax Region](https://docs.medusajs.com/api/admin#tax-regions_posttaxregions)
    * API route.
-   * 
+   *
    * @param body - The details of the tax region to create.
    * @param query - Configure the fields and relations to retrieve in the tax region.
    * @param headers - Headers to pass in the request.
    * @returns The tax region's details.
-   * 
+   *
    * @example
    * sdk.admin.taxRegion.create({
    *   country_code: "us",
@@ -62,15 +62,51 @@ export class TaxRegion {
     )
   }
 
+  /**
+   * This method updates a tax region. It sends a request to the
+   * [Update Tax Region](https://docs.medusajs.com/api/admin#tax-regions_posttaxregionsid)
+   * API route.
+   *
+   * @param id - The ID of the tax region to update.
+   * @param body - The details of the tax region to update.
+   * @param query - Configure the fields and relations to retrieve in the tax region.
+   * @param headers - Headers to pass in the request.
+   * @returns The tax region's details.
+   *
+   * @example
+   * sdk.admin.taxRegion.update("txreg_123", {
+   *   province_code: "ca",
+   * })
+   * .then(({ tax_region }) => {
+   *   console.log(tax_region)
+   * })
+   */
+  async update(
+    id: string,
+    body: HttpTypes.AdminUpdateTaxRegion,
+    query?: HttpTypes.SelectParams,
+    headers?: ClientHeaders
+  ) {
+    return await this.client.fetch<HttpTypes.AdminTaxRegionResponse>(
+      `${taxRegionUrl}/${id}`,
+      {
+        method: "POST",
+        headers,
+        body,
+        query,
+      }
+    )
+  }
+
   /**
    * This method deletes a tax region. It sends a request to the
    * [Delete Tax Region](https://docs.medusajs.com/api/admin#tax-regions_deletetaxregionsid)
    * API route.
-   * 
+   *
    * @param id - The ID of the tax region to delete.
    * @param headers - Headers to pass in the request.
    * @returns The deletion's details.
-   * 
+   *
    * @example
    * sdk.admin.taxRegion.delete("txreg_123")
    * .then(({ deleted }) => {
@@ -91,24 +127,24 @@ export class TaxRegion {
    * This method retrieves a tax region. It sends a request to the
    * [Get Tax Region](https://docs.medusajs.com/api/admin#tax-regions_gettaxregionsid)
    * API route.
-   * 
+   *
    * @param id - The ID of the tax region to retrieve.
    * @param query - Configure the fields and relations to retrieve in the tax region.
    * @param headers - Headers to pass in the request.
    * @returns The tax region's details.
-   * 
+   *
    * @example
    * To retrieve a tax region by its ID:
-   * 
+   *
    * ```ts
    * sdk.admin.taxRegion.retrieve("txreg_123")
    * .then(({ tax_region }) => {
    *   console.log(tax_region)
    * })
    * ```
-   * 
+   *
    * To specify the fields and relations to retrieve:
-   * 
+   *
    * ```ts
    * sdk.admin.taxRegion.retrieve("txreg_123", {
    *   fields: "id,*tax_rates"
@@ -117,7 +153,7 @@ export class TaxRegion {
    *   console.log(tax_region)
    * })
    * ```
-   * 
+   *
    * Learn more about the `fields` property in the [API reference](https://docs.medusajs.com/api/admin#select-fields-and-relations).
    */
   async retrieve(
@@ -139,25 +175,25 @@ export class TaxRegion {
    * This method retrieves a list of tax regions. It sends a request to the
    * [List Tax Regions](https://docs.medusajs.com/api/admin#tax-regions_gettaxregions)
    * API route.
-   * 
+   *
    * @param query - Filters and pagination configurations.
    * @param headers - Headers to pass in the request.
    * @returns The list of tax regions.
-   * 
+   *
    * @example
    * To retrieve the list of tax regions:
-   * 
+   *
    * ```ts
    * sdk.admin.taxRegion.list()
    * .then(({ tax_regions, count, limit, offset }) => {
    *   console.log(tax_regions)
    * })
    * ```
-   * 
+   *
    * To configure the pagination, pass the `limit` and `offset` query parameters.
-   * 
+   *
    * For example, to retrieve only 10 items and skip 10 items:
-   * 
+   *
    * ```ts
    * sdk.admin.taxRegion.list({
    *   limit: 10,
@@ -167,10 +203,10 @@ export class TaxRegion {
    *   console.log(tax_regions)
    * })
    * ```
-   * 
+   *
    * Using the `fields` query parameter, you can specify the fields and relations to retrieve
    * in each tax region:
-   * 
+   *
    * ```ts
    * sdk.admin.taxRegion.list({
    *   fields: "id,*tax_rates"
@@ -179,7 +215,7 @@ export class TaxRegion {
    *   console.log(tax_regions)
    * })
    * ```
-   * 
+   *
    * Learn more about the `fields` property in the [API reference](https://docs.medusajs.com/api/admin#select-fields-and-relations).
    */
   async list(

packages/core/types/src/http/index.ts

@@ -39,6 +39,7 @@ export * from "./shipping-option"
 export * from "./shipping-profile"
 export * from "./stock-locations"
 export * from "./store"
+export * from "./tax-provider"
 export * from "./tax-rate"
 export * from "./tax-region"
 export * from "./user"

packages/core/types/src/http/tax-provider/admin/entities.ts

@@ -0,0 +1,10 @@
+export interface AdminTaxProvider {
+  /**
+   * The ID of the tax provider.
+   */
+  id: string
+  /**
+   * Whether the tax provider is enabled.
+   */
+  is_enabled: boolean
+}

packages/core/types/src/http/tax-provider/admin/index.ts

@@ -0,0 +1,3 @@
+export * from "./entities"
+export * from "./queries"
+export * from "./responses"

packages/core/types/src/http/tax-provider/admin/queries.ts

@@ -0,0 +1,15 @@
+import { BaseFilterable } from "../../../dal"
+import { FindParams } from "../../common"
+
+export interface AdminGetTaxProvidersParams
+  extends FindParams,
+    BaseFilterable<AdminGetTaxProvidersParams> {
+  /**
+   * Filter by tax provider ID(s).
+   */
+  id?: string | string[]
+  /**
+   * Whether the tax provider is enabled.
+   */
+  is_enabled?: boolean
+}

packages/core/types/src/http/tax-provider/admin/responses.ts

@@ -0,0 +1,9 @@
+import { PaginatedResponse } from "../../common"
+import { AdminTaxProvider } from "./entities"
+
+export type AdminTaxProviderListResponse = PaginatedResponse<{
+  /**
+   * The list of tax providers.
+   */
+  tax_providers: AdminTaxProvider[]
+}>

packages/core/types/src/http/tax-provider/index.ts

@@ -0,0 +1 @@
+export * from "./admin"

packages/core/types/src/http/tax-region/admin/entities.ts

@@ -7,14 +7,14 @@ export interface AdminTaxRegion {
   id: string
   /**
    * The tax region's country code.
-   * 
+   *
    * @example
    * "us"
    */
   country_code: string | null
   /**
    * The tax region's lower-case [ISO 3166-2](https://en.wikipedia.org/wiki/ISO_3166-2) province or state code.
-   * 
+   *
    * @example
    * "us-ca"
    */
@@ -27,6 +27,10 @@ export interface AdminTaxRegion {
    * The ID of the parent tax region.
    */
   parent_id: string | null
+  /**
+   * The ID of the tax provider for the region.
+   */
+  provider_id: string | null
   /**
    * The date the tax region was created.
    */

packages/core/types/src/http/tax-region/admin/payloads.ts

@@ -3,6 +3,10 @@ export interface AdminCreateTaxRegion {
    * The country code of the tax region.
    */
   country_code: string
+  /**
+   * The ID of the tax provider.
+   */
+  provider_id?: string
   /**
    * The lower-case [ISO 3166-2](https://en.wikipedia.org/wiki/ISO_3166-2) province or state code of the tax region.
    */
@@ -41,3 +45,21 @@ export interface AdminCreateTaxRegion {
    */
   metadata?: Record<string, unknown>
 }
+
+export interface AdminUpdateTaxRegion {
+  /**
+   * The lower-case [ISO 3166-2](https://en.wikipedia.org/wiki/ISO_3166-2) province or state code of the tax region.
+   */
+  province_code?: string
+  /**
+   * The ID of the tax provider.
+   */
+  provider_id?: string
+  /**
+   * Custom key-value pairs that can be added to the tax region.
+   */
+  /**
+   * Custom key-value pairs that can be added to the tax region.
+   */
+  metadata?: Record<string, unknown>
+}

packages/core/types/src/tax/common.ts

@@ -163,6 +163,11 @@ export interface TaxRegionDTO {
    */
   parent_id: string | null
 
+  /**
+   * The ID of the tax provider for the region.
+   */
+  provider_id: string | null
+
   /**
    * Holds custom data in key-value pairs.
    */

packages/core/types/src/tax/mutations.ts

@@ -1,4 +1,7 @@
 import { MetadataType } from "../common"
+import { BaseFilterable } from "../dal"
+import { OperatorMap } from "../dal"
+import { TaxProviderDTO } from "./common"
 
 /**
  * The tax rate to be created.
@@ -49,6 +52,37 @@ export interface CreateTaxRateDTO {
   metadata?: MetadataType
 }
 
+/**
+ * The tax provider to be created.
+ */
+export interface CreateTaxProviderDTO {
+  /**
+   * The provider's ID.
+   */
+  id: string
+
+  /**
+   * Whether the provider is enabled.
+   */
+  is_enabled?: boolean
+}
+
+/**
+ * The filters to apply on the retrieved tax providers.
+ */
+export interface FilterableTaxProviderProps
+  extends BaseFilterable<TaxProviderDTO> {
+  /**
+   * The IDs to filter the tax provider by.
+   */
+  id?: string | string[] | OperatorMap<string | string[]>
+
+  /**
+   * Filter by whether the tax provider is enabled.
+   */
+  is_enabled?: boolean
+}
+
 /**
  * The attributes in the tax rate to be created or updated.
  */
@@ -166,6 +200,11 @@ export interface CreateTaxRegionDTO {
    */
   parent_id?: string | null
 
+  /**
+   * The ID of the tax provider for the region.
+   */
+  provider_id?: string | null
+
   /**
    * Holds custom data in key-value pairs.
    */
@@ -220,6 +259,11 @@ export interface UpdateTaxRegionDTO {
    */
   province_code?: string | null
 
+  /**
+   * The ID of the tax provider for the region.
+   */
+  provider_id?: string | null
+
   /**
    * Holds custom data in key-value pairs.
    */

packages/core/types/src/tax/service.ts

@@ -11,6 +11,7 @@ import {
   TaxableItemDTO,
   TaxableShippingDTO,
   TaxCalculationContext,
+  TaxProviderDTO,
   TaxRateDTO,
   TaxRateRuleDTO,
   TaxRegionDTO,
@@ -19,6 +20,7 @@ import {
   CreateTaxRateDTO,
   CreateTaxRateRuleDTO,
   CreateTaxRegionDTO,
+  FilterableTaxProviderProps,
   UpdateTaxRateDTO,
   UpdateTaxRegionDTO,
   UpsertTaxRateDTO,
@@ -580,6 +582,24 @@ export interface ITaxModuleService extends IModuleService {
     sharedContext?: Context
   ): Promise<TaxRateRuleDTO>
 
+  /**
+   * This method retrieves a paginated list of tax providers based on optional filters and configuration.
+   *
+   * @param {FilterableTaxProviderProps} filters - The filters to apply on the retrieved tax providers.
+   * @param {FindConfig<TaxProviderDTO>} config - The configurations determining how the tax provider is retrieved.
+   * @param {Context} sharedContext - A context used to share resources, such as transaction manager, between the application and the module.
+   * @returns {Promise<TaxProviderDTO[]>} The list of tax providers.
+   *
+   * @example
+   * const taxProviders = await taxModuleService.listTaxProviders()
+   */
+
+  listTaxProviders(
+    filters?: FilterableTaxProviderProps,
+    config?: FindConfig<TaxProviderDTO>,
+    sharedContext?: Context
+  ): Promise<TaxProviderDTO[]>
+
   /**
    * This method creates tax rate rules.
    *