feat(tax): Add TaxRegion (#6421)

**What**
- Adds a TaxRegion entity.

**For context: High-level design of the Tax module**
- A TaxRegion scopes tax rates to a geographical place.
- You can define tax regions on two levels: country-level, province-level (this corresponds to state in US contexts)
- Each Tax Region can have a default Tax Rate.
-  [not yet done] - Each Tax Region can also have granularly defined tax rates for different products and shipping rates. For example, California can have a base rate for default products, but a reduced rate for groceries.
- Tax Rates specify if they can be combined with other rates - it's always the lowest level rate that wins.

The above allows a merchant to define their tax settings along the lines of this:

- Denmark (Region)
  - Default rate: 25% (TaxRate)
- Germany (Region)
  - Default rate: 19% (TaxRate)
  - Reduced rate (books): 9% (TaxRate w. rule)
- United States (Region)
  - Default rate: 0% (TaxRate)
  - California: (Region)
    - Default rate: 7.25% (TaxRate)
  - Arkansas: (Region)
    - Default rate: 6.5%
    - Reduced rate (groceries): 0.125% (TaxRate w. rule)

The TaxModule can then receive a list of products and the shipping address to determine what tax rates apply to the line items.

packages/types/src/tax/common.ts

@@ -47,3 +47,29 @@ export interface FilterableTaxRateProps
   updated_at?: OperatorMap<string>
   created_by?: string | string[] | OperatorMap<string>
 }
+
+export interface TaxRegionDTO {
+  id: string
+  country_code: string
+  province_code: string | null
+  parent_id: string | null
+  metadata: Record<string, unknown> | null
+  created_at: string | Date
+  updated_at: string | Date
+  created_by: string | null
+}
+
+export interface FilterableTaxRegionProps
+  extends BaseFilterable<FilterableTaxRegionProps> {
+  id?: string | string[]
+  country_code?: string | string[] | OperatorMap<string>
+  province_code?: string | string[] | OperatorMap<string>
+  parent_id?: string | string[] | OperatorMap<string>
+  metadata?:
+    | Record<string, unknown>
+    | Record<string, unknown>[]
+    | OperatorMap<Record<string, unknown>>
+  created_at?: OperatorMap<string>
+  updated_at?: OperatorMap<string>
+  created_by?: string | string[] | OperatorMap<string>
+}

packages/types/src/tax/mutations.ts

@@ -1,7 +1,23 @@
 export interface CreateTaxRateDTO {
+  tax_region_id: string
   rate?: number | null
   code?: string | null
   name: string
+  is_default?: boolean
   created_by?: string
   metadata?: Record<string, unknown>
 }
+
+export interface CreateTaxRegionDTO {
+  country_code: string
+  province_code?: string | null
+  parent_id?: string | null
+  metadata?: Record<string, unknown>
+  created_by?: string
+  default_tax_rate: {
+    rate?: number | null
+    code?: string | null
+    name: string
+    metadata?: Record<string, unknown>
+  }
+}

packages/types/src/tax/service.ts

@@ -1,10 +1,15 @@
 import { FindConfig } from "../common"
 import { IModuleService } from "../modules-sdk"
 import { Context } from "../shared-context"
-import { FilterableTaxRateProps, TaxRateDTO } from "./common"
-import { CreateTaxRateDTO } from "./mutations"
+import {
+  FilterableTaxRegionProps,
+  FilterableTaxRateProps,
+  TaxRateDTO,
+  TaxRegionDTO,
+} from "./common"
+import { CreateTaxRateDTO, CreateTaxRegionDTO } from "./mutations"
 
-export interface ITaxRateModuleService extends IModuleService {
+export interface ITaxModuleService extends IModuleService {
   retrieve(
     taxRateId: string,
     config?: FindConfig<TaxRateDTO>,
@@ -31,4 +36,15 @@ export interface ITaxRateModuleService extends IModuleService {
 
   delete(taxRateIds: string[], sharedContext?: Context): Promise<void>
   delete(taxRateId: string, sharedContext?: Context): Promise<void>
+
+  createTaxRegions(
+    data: CreateTaxRegionDTO[],
+    sharedContext?: Context
+  ): Promise<TaxRegionDTO[]>
+
+  listTaxRegions(
+    filters?: FilterableTaxRegionProps,
+    config?: FindConfig<TaxRegionDTO>,
+    sharedContext?: Context
+  ): Promise<TaxRegionDTO[]>
 }