asyavee/medusa-store
1
0
Fork 0
Code Issues Pull Requests Actions 2 Packages Projects Releases Wiki Activity

chore: added tsdocs for the Tax Module (#6902)

Browse Source
This commit is contained in:
Shahed Nasser
2024-04-05 13:03:03 +03:00
committed by GitHub
parent 3507e5e263
commit bd2c5aca16
4 changed files with 1298 additions and 10 deletions
Download Patch File Download Diff File Expand all files Collapse all files

384
packages/types/src/tax/common.ts
View File

@@ -1,177 +1,541 @@
import { BaseFilterable } from "../dal"
import { OperatorMap } from "../dal/utils"
/**
* The tax rate details.
*/
export interface TaxRateDTO {
/**
* The ID of the Tax Rate.
* The ID of the tax rate.
*/
id: string
/**
* The numerical rate to charge.
* The rate to charge.
* @example
* 10
*/
rate: number | null
/**
* The code the tax rate is identified by.
*/
code: string | null
/**
* The name of the Tax Rate. E.g. "VAT".
* The name of the Tax Rate.
* @example
* VAT
*/
name: string
/**
* Holds custom data in key-value pairs.
*/
metadata: Record<string, unknown> | null
/**
* The id of the Tax Region the rate is associated with.
* The ID of the associated tax region.
*/
tax_region_id: string
/**
* Flag to indicate if the Tax Rate should be combined with parent rates.
* Whether the tax rate should be combined with parent rates.
*
* Learn more [here](https://docs.medusajs.com/experimental/tax/tax-rates-and-rules/#combinable-tax-rates).
*/
is_combinable: boolean
/**
* Flag to indicate if the Tax Rate is the default rate for the region.
* Whether the tax rate is the default rate for the region.
*/
is_default: boolean
/**
* When the Tax Rate was created.
* The creation date of the tax rate.
*/
created_at: string | Date
/**
* When the Tax Rate was updated.
* The update date of the tax rate.
*/
updated_at: string | Date
/**
* When the Tax Rate was deleted.
* The deletion date of the tax rate.
*/
deleted_at: Date | null
/**
* The ID of the user that created the Tax Rate.
* Who created the tax rate. For example, the ID of the user that created the tax rate.
*/
created_by: string | null
}
/**
* The tax provider details.
*/
export interface TaxProviderDTO {
/**
* The ID of the tax provider.
*/
id: string
/**
* Whether the tax provider is enabled.
*/
is_enabled: boolean
}
/**
* The filters to apply on the retrieved tax rates.
*/
export interface FilterableTaxRateProps
extends BaseFilterable<FilterableTaxRateProps> {
/**
* The IDs to filter the tax rates by.
*/
id?: string | string[]
/**
* Filter the tax rates by their associated tax regions.
*/
tax_region_id?: string | string[]
/**
* Filter the tax rates by their rate.
*/
rate?: number | number[] | OperatorMap<number>
/**
* Filter the tax rates by their code.
*/
code?: string | string[] | OperatorMap<string>
/**
* Filter the tax rates by their name.
*/
name?: string | string[] | OperatorMap<string>
/**
* Filter the tax rates by their creation date.
*/
created_at?: OperatorMap<string>
/**
* Filter the tax rates by their update date.
*/
updated_at?: OperatorMap<string>
/**
* Filter the tax rates by who created it.
*/
created_by?: string | string[] | OperatorMap<string>
}
/**
* The tax region details.
*/
export interface TaxRegionDTO {
/**
* The ID of the tax region.
*/
id: string
/**
* The ISO 2 character country code of the tax region.
*/
country_code: string
/**
* The province code of the tax region.
*/
province_code: string | null
/**
* The ID of the tax region's parent tax region.
*/
parent_id: string | null
/**
* Holds custom data in key-value pairs.
*/
metadata: Record<string, unknown> | null
/**
* The creation date of the tax region.
*/
created_at: string | Date
/**
* The update date of the tax region.
*/
updated_at: string | Date
/**
* Who created the tax region. For example, the ID of the user
* that created the tax region.
*/
created_by: string | null
/**
* The deletion date of the tax region.
*/
deleted_at: string | Date | null
}
/**
* The filters to apply on the retrieved tax regions.
*/
export interface FilterableTaxRegionProps
extends BaseFilterable<FilterableTaxRegionProps> {
/**
* The IDs to filter the tax regions by.
*/
id?: string | string[]
/**
* Filter the tax regions by their country code.
*/
country_code?: string | string[] | OperatorMap<string>
/**
* Filter the tax regions by their province code.
*/
province_code?: string | string[] | OperatorMap<string>
/**
* Filter the tax regions by the ID of their parent tax region.
*/
parent_id?: string | string[] | OperatorMap<string>
/**
* Filter the tax regions by their metadata.
*/
metadata?:
| Record<string, unknown>
| Record<string, unknown>[]
| OperatorMap<Record<string, unknown>>
/**
* Filter the tax regions by their creation date.
*/
created_at?: OperatorMap<string>
/**
* Filter the tax regions by their update date.
*/
updated_at?: OperatorMap<string>
/**
* Filter the tax regions by who created it.
*/
created_by?: string | string[] | OperatorMap<string>
}
/**
* The tax rate rule details.
*/
export interface TaxRateRuleDTO {
/**
* The ID of the tax rate rule.
*/
id: string
/**
* The snake-case name of the data model that the tax rule references.
* For example, `product`.
*
* Learn more in [this guide](https://docs.medusajs.com/experimental/tax/tax-rates-and-rules/#what-are-tax-rules).
*/
reference: string
/**
* The ID of the record of the data model that the tax rule references.
* For example, `prod_123`.
*
* Learn more in [this guide](https://docs.medusajs.com/experimental/tax/tax-rates-and-rules/#what-are-tax-rules).
*/
reference_id: string
/**
* The associated tax rate's ID.
*/
tax_rate_id: string
/**
* The associated tax rate.
*/
tax_rate?: TaxRateDTO
/**
* Holds custom data in key-value pairs.
*/
metadata?: Record<string, unknown> | null
/**
* The creation date of the tax rate rule.
*/
created_at: string | Date
/**
* The update date of the tax rate rule.
*/
updated_at: string | Date
/**
* Who created the tax rate rule. For example, the ID of the user
* that created the tax rate rule.
*/
created_by: string | null
}
/**
* The filters to apply on the retrieved tax rate rules.
*/
export interface FilterableTaxRateRuleProps
extends BaseFilterable<FilterableTaxRateRuleProps> {
/**
* Filter the tax rate rule by what it references.
*/
reference?: string | string[] | OperatorMap<string>
/**
* Filter the tax rate rule by the ID of the record it references.
*/
reference_id?: string | string[] | OperatorMap<string>
/**
* Filter the tax rate rule by the ID of their associated tax rate.
*/
tax_rate_id?: string | string[] | OperatorMap<string>
/**
* Filter the tax rate rule by their associated tax rate.
*/
tax_rate?: FilterableTaxRateProps
/**
* Filter the tax rate rule by what its metadata.
*/
metadata?:
| Record<string, unknown>
| Record<string, unknown>[]
| OperatorMap<Record<string, unknown>>
/**
* Filter the tax rate rule by its creation date.
*/
created_at?: OperatorMap<string>
/**
* Filter the tax rate rule by its update date.
*/
updated_at?: OperatorMap<string>
/**
* Filter the tax rate rule by who created it.
*/
created_by?: string | string[] | OperatorMap<string>
}
/**
* The taxable item details.
*/
export interface TaxableItemDTO {
/**
* The ID of the taxable item.
*/
id: string
/**
* The associated product's ID.
*/
product_id: string
/**
* The name of the item's product.
*/
product_name?: string
/**
* The ID of the category of the item's product.
*/
product_category_id?: string
/**
* The categories of the item's product.
*/
product_categories?: string[]
/**
* The SKU of the item's product.
*/
product_sku?: string
/**
* The type of the item's product.
*/
product_type?: string
/**
* The ID of the type of the item's product.
*/
product_type_id?: string
/**
* The quantity of the taxable item.
*/
quantity?: number
/**
* The unit price of the taxable item.
*/
unit_price?: number
/**
* The ISO 3 character currency code of the taxable item.
*/
currency_code?: string
}
/**
* The taxable shipping details.
*/
export interface TaxableShippingDTO {
/**
* The ID of the taxable shipping.
*/
id: string
/**
* The associated shipping option's ID.
*/
shipping_option_id: string
/**
* The unit price of the taxable shipping.
*/
unit_price?: number
/**
* The ISO 3 character currency code of the taxable shipping.
*/
currency_code?: string
}
/**
* The context provided when tax lines are calculated and retrieved. This
* context is later passed to the underlying tax provider.
*/
export interface TaxCalculationContext {
/**
* The customer's address
*/
address: {
/**
* The ISO 2 character currency code.
*/
country_code: string
/**
* The province code.
*/
province_code?: string | null
/**
* The first line of the address.
*/
address_1?: string
/**
* The second line of the address
*/
address_2?: string | null
/**
* The city.
*/
city?: string
/**
* The postal code.
*/
postal_code?: string
}
/**
* The customer's details.
*/
customer?: {
/**
* The ID of the customer.
*/
id: string
/**
* The email of the customer.
*/
email: string
/**
* The groups that the customer belongs to.
*/
customer_groups: string[]
}
/**
* Whether the tax lines are calculated for an order return.
*/
is_return?: boolean
}
/**
* The tax line details.
*/
interface TaxLineDTO {
/**
* The associated rate's ID.
*/
rate_id?: string
/**
* The rate of the tax line.
*/
rate: number | null
/**
* The code of the tax line.
*/
code: string | null
/**
* The name of the tax line.
*/
name: string
/**
* The ID of the tax provider used to calculate and retrieve the tax line.
*/
provider_id: string
}
/**
* The item tax line details.
*/
export interface ItemTaxLineDTO extends TaxLineDTO {
/**
* The associated line item's ID.
*/
line_item_id: string
}
/**
* The shipping tax line details.
*/
export interface ShippingTaxLineDTO extends TaxLineDTO {
/**
* The associated shipping line's ID.
*/
shipping_line_id: string
}

189
packages/types/src/tax/mutations.ts
View File

@@ -1,53 +1,242 @@
/**
* The tax rate to be created.
*/
export interface CreateTaxRateDTO {
/**
* The associated tax region's ID.
*/
tax_region_id: string
/**
* The rate to charge.
*
* @example
* 10
*/
rate?: number | null
/**
* The code of the tax rate.
*/
code?: string | null
/**
* The name of the tax rate.
*/
name: string
/**
* The rules of the tax rate.
*/
rules?: Omit<CreateTaxRateRuleDTO, "tax_rate_id">[]
/**
* Whether the tax rate is default.
*/
is_default?: boolean
/**
* Who created the tax rate. For example, the ID of the user
* that created the tax rate.
*/
created_by?: string
/**
* Holds custom data in key-value pairs.
*/
metadata?: Record<string, unknown>
}
/**
* The attributes in the tax rate to be created or updated.
*/
export interface UpsertTaxRateDTO {
/**
* The ID of the tax rate. If not provided, the tax rate
* is created.
*/
id?: string
/**
* The rate to charge
*
* @example
* 10
*/
rate?: number | null
/**
* The code of the tax rate.
*/
code?: string | null
/**
* The name of the tax rate.
*/
name?: string
/**
* Whether the tax rate is default.
*/
is_default?: boolean
/**
* Who created the tax rate. For example, the
* ID of the user that created it.
*/
created_by?: string | null
/**
* Holds custom data in key-value pairs.
*/
metadata?: Record<string, unknown> | null
}
/**
* The attributes to update in the tax rate.
*/
export interface UpdateTaxRateDTO {
/**
* The rate to charge.
*
* @example
* 10
*/
rate?: number | null
/**
* The code of the tax rate.
*/
code?: string | null
/**
* The name of the tax rate.
*/
name?: string
/**
* The rules of the tax rate.
*/
rules?: Omit<CreateTaxRateRuleDTO, "tax_rate_id">[]
/**
* Whether the tax rate is default.
*/
is_default?: boolean
/**
* Whether the tax rate is combinable.
*
* Learn more [here](https://docs.medusajs.com/experimental/tax/tax-rates-and-rules/#combinable-tax-rates).
*/
is_combinable?: boolean
/**
* @ignore
*
* @privateRemarks
* This should be `created_by`.
*/
updated_by?: string
/**
* Holds custom data in key-value pairs.
*/
metadata?: Record<string, unknown>
}
/**
* The tax region to be created.
*/
export interface CreateTaxRegionDTO {
/**
* The ISO 3 character country code of the tax region.
*/
country_code: string
/**
* The province code of the tax region.
*/
province_code?: string | null
/**
* The ID of the tax region's parent.
*/
parent_id?: string | null
/**
* Holds custom data in key-value pairs.
*/
metadata?: Record<string, unknown>
/**
* Who created the tax region. For example, the ID of
* the user that created the tax region.
*/
created_by?: string
/**
* The default tax rate of the tax region.
*/
default_tax_rate?: {
/**
* The rate to charge.
*
* @example
* 10
*/
rate?: number | null
/**
* The code of the tax rate.
*/
code?: string | null
/**
* The name of the tax rate.
*/
name: string
/**
* Holds custom data in key-value pairs.
*/
metadata?: Record<string, unknown>
}
}
/**
* The tax rate rule to be created.
*/
export interface CreateTaxRateRuleDTO {
/**
* The snake-case name of the data model that the tax rule references.
* For example, `product`.
*
* Learn more in [this guide](https://docs.medusajs.com/experimental/tax/tax-rates-and-rules/#what-are-tax-rules).
*/
reference: string
/**
* The ID of the record of the data model that the tax rule references.
* For example, `prod_123`.
*
* Learn more in [this guide](https://docs.medusajs.com/experimental/tax/tax-rates-and-rules/#what-are-tax-rules).
*/
reference_id: string
/**
* The associated tax rate's ID.
*/
tax_rate_id: string
/**
* Holds custom data in key-value pairs.
*/
metadata?: Record<string, unknown>
/**
* Who created the tax rate rule. For example, the ID of the
* user that created it.
*/
created_by?: string | null
}

126
packages/types/src/tax/provider.ts
View File

@@ -37,9 +37,135 @@ export type ItemTaxCalculationLine = {
rates: TaxRateDTO[]
}
/**
* ## Overview
*
* A tax provider is used to retrieve the tax lines in a provided context. The Tax Module provides a default `system` provider. You can create your own tax provider,
* either in a plugin, in a provider module, or directly in your Medusa application's codebase, then use it in any tax region.
*
* ---
*
* ## How to Create a Tax Provider
*
* A tax provider class is defined in a TypeScript or JavaScript file. The class must implement the
* `ITaxProvider` interface imported from `@medusajs/types`.
*
* The file can be defined in a plugin, a provider module, or under the `src/services` directory of your Medusa application. You can later pass the package's name or the
* path to the file in the `providers` option of the Tax Module.
*
* For example:
*
* ```ts title="src/services/my-tax.ts"
* import { ITaxProvider } from "@medusajs/types"
*
* export default class MyTaxProvider implements ITaxProvider {
* // ...
* }
* ```
*
* ---
*
* ## Identifier Property
*
* The `identifier` property in a tax provider is used when the tax provider is registered in the dependency container or added to the database. A tax provider is represented in the database by the `TaxProvider` data model.
*
* For example:
*
* ```ts title="src/services/my-tax.ts"
* export default class MyTaxProvider implements ITaxProvider {
* static identifier = "my-tax"
* // ...
* }
* ```
*
* ---
*
* ## Constructor
*
* You can use the `constructor` of your tax provider to access the resources registered in the dependency container.
*
* You can also use the constructor to initialize your integration with the third-party provider. For example, if you use a client to connect to the third-party provider’s APIs, you can initialize it in the constructor and use it in other methods in the service.
*
* Additionally, if you’re creating your tax provider as a plugin or a provider module to be installed in any Medusa application and you want to access its options, you can access them in the constructor.
*
* For example:
*
* export default class MyTaxProvider implements ITaxProvider {
* // ...
* constructor(container, options) {
* // you can access options here
*
* // you can also initialize a client that
* // communicates with a third-party service.
* this.client = new Client(options)
* }
* }
*
* ---
*/
export interface ITaxProvider {
/**
* @ignore
*/
getIdentifier(): string
/**
* This method is used to retrieve the tax lines of items and shipping methods. It's used
* when the `getTaxLines` method of the Tax Module's main service is called.
*
* This method is useful during checkout or when calculating the totals of orders or exchanges.
*
* @param {ItemTaxCalculationLine[]} itemLines - The line item lines to calculate taxes for.
* @param {ShippingTaxCalculationLine[]} shippingLines - The shipping method lines to calculate taxes for.
* @param {TaxCalculationContext} context - The context relevant and useful for the taxes calculation.
* @return {Promise<(ItemTaxLineDTO | ShippingTaxLineDTO)[]>} The list of calculated line item and shipping tax lines.
* If an item in the array has the `shipping_line_id` property, then it's a shipping tax line. Otherwise, if it has
* the `line_item_id` property, then it's a line item tax line.
*
* @example
* An example of how this method is implemented in the `system` provider:
*
* ```ts
* // ...
*
* export default class SystemTaxService implements ITaxProvider {
* // ...
*
* async getTaxLines(
* itemLines: TaxTypes.ItemTaxCalculationLine[],
* shippingLines: TaxTypes.ShippingTaxCalculationLine[],
* _: TaxTypes.TaxCalculationContext
* ): Promise<(TaxTypes.ItemTaxLineDTO | TaxTypes.ShippingTaxLineDTO)[]> {
* let taxLines: (TaxTypes.ItemTaxLineDTO | TaxTypes.ShippingTaxLineDTO)[] =
* itemLines.flatMap((l) => {
* return l.rates.map((r) => ({
* rate_id: r.id,
* rate: r.rate || 0,
* name: r.name,
* code: r.code,
* line_item_id: l.line_item.id,
* provider_id: this.getIdentifier(),
* }))
* })
*
* taxLines = taxLines.concat(
* shippingLines.flatMap((l) => {
* return l.rates.map((r) => ({
* rate_id: r.id,
* rate: r.rate || 0,
* name: r.name,
* code: r.code,
* shipping_line_id: l.shipping_line.id,
* provider_id: this.getIdentifier(),
* }))
* })
* )
*
* return taxLines
* }
* }
* ```
*/
getTaxLines(
itemLines: ItemTaxCalculationLine[],
shippingLines: ShippingTaxCalculationLine[],

609
packages/types/src/tax/service.ts
View File

@@ -23,137 +23,746 @@ import {
UpsertTaxRateDTO,
} from "./mutations"
/**
* The main service interface for the Tax Module.
*/
export interface ITaxModuleService extends IModuleService {
/**
* This method retrieves a tax by its ID.
*
* @param {string} taxRateId - The tax rate's ID.
* @param {FindConfig<TaxRateDTO>} config - The configurations determining how the tax rate is retrieved. Its properties, such as `select` or `relations`, accept the
* attributes or relations associated with a tax rate.
* @param {Context} sharedContext - A context used to share resources, such as transaction manager, between the application and the module.
* @returns {Promise<TaxRateDTO>} The retrieved tax.
*
* @example
* A simple example that retrieves a tax rate by its ID:
*
* ```ts
* const taxRate = await taxModuleService.retrieve("txr_123")
* ```
*
* To specify relations that should be retrieved:
*
* ```ts
* const taxRate = await taxModuleService.retrieve("txr_123", {
* relations: ["tax_region"],
* })
* ```
*/
retrieve(
taxRateId: string,
config?: FindConfig<TaxRateDTO>,
sharedContext?: Context
): Promise<TaxRateDTO>
/**
* This method retrieves a paginated list of tax rates based on optional filters and configuration.
*
* @param {FilterableTaxRateProps} filters - The filters to apply on the retrieved tax rates.
* @param {FindConfig<TaxRateDTO>} config - The configurations determining how the tax rate is retrieved. Its properties, such as `select` or `relations`, accept the
* attributes or relations associated with a tax rate.
* @param {Context} sharedContext - A context used to share resources, such as transaction manager, between the application and the module.
* @returns {Promise<TaxRateDTO[]>} The list of tax rates.
*
* @example
* To retrieve a list of tax rates using their IDs:
*
* ```ts
* const taxRates = await taxModuleService.list({
* id: ["txr_123", "txr_321"],
* })
* ```
*
* To specify relations that should be retrieved within the tax rate:
*
* ```ts
* const taxRates = await taxModuleService.list(
* {
* id: ["txr_123", "txr_321"],
* },
* {
* relations: ["tax_region"],
* }
* )
* ```
*
* By default, only the first `15` records are retrieved. You can control pagination by specifying the `skip` and `take` properties of the `config` parameter:
*
* ```ts
* const taxRates = await taxModuleService.list(
* {
* id: ["txr_123", "txr_321"],
* },
* {
* relations: ["tax_region"],
* take: 20,
* skip: 2,
* }
* )
* ```
*/
list(
filters?: FilterableTaxRateProps,
config?: FindConfig<TaxRateDTO>,
sharedContext?: Context
): Promise<TaxRateDTO[]>
/**
* This method retrieves a paginated list of tax rates along with the total count of available tax rates satisfying the provided filters.
*
* @param {FilterableTaxRateProps} filters - The filters to apply on the retrieved tax rates.
* @param {FindConfig<TaxRateDTO>} config - The configurations determining how the tax rate is retrieved. Its properties, such as `select` or `relations`, accept the
* attributes or relations associated with a tax rate.
* @param {Context} sharedContext - A context used to share resources, such as transaction manager, between the application and the module.
* @returns {Promise<[TaxRateDTO[], number]>} The list of tax rates along with their total count.
*
* @example
* To retrieve a list of tax rates using their IDs:
*
* ```ts
* const [taxRates, count] = await taxModuleService.listAndCount(
* {
* id: ["txr_123", "txr_321"],
* }
* )
* ```
*
* To specify relations that should be retrieved within the tax rate:
*
* ```ts
* const [taxRates, count] = await taxModuleService.listAndCount(
* {
* id: ["txr_123", "txr_321"],
* },
* {
* relations: ["tax_region"],
* }
* )
* ```
*
* By default, only the first `15` records are retrieved. You can control pagination by specifying the `skip` and `take` properties of the `config` parameter:
*
* ```ts
* const [taxRates, count] = await taxModuleService.listAndCount(
* {
* id: ["txr_123", "txr_321"],
* },
* {
* relations: ["tax_region"],
* take: 20,
* skip: 2,
* }
* )
* ```
*/
listAndCount(
filters?: FilterableTaxRateProps,
config?: FindConfig<TaxRateDTO>,
sharedContext?: Context
): Promise<[TaxRateDTO[], number]>
/**
* This method creates tax rates.
*
* @param {CreateTaxRateDTO[]} data - The tax rates to be created.
* @param {Context} sharedContext - A context used to share resources, such as transaction manager, between the application and the module.
* @returns {Promise<TaxRateDTO[]>} The created tax rates.
*
* @example
* const taxRates = await taxModuleService.create([
* {
* tax_region_id: "txreg_123",
* name: "Default rate",
* rate: 10,
* },
* {
* tax_region_id: "txreg_123",
* name: "Custom rate",
* rate: 15,
* rules: [
* {
* reference: "product_type",
* reference_id: "ptyp_1",
* },
* {
* reference: "product",
* reference_id: "prod_123",
* },
* ],
* },
* ])
*/
create(
data: CreateTaxRateDTO[],
sharedContext?: Context
): Promise<TaxRateDTO[]>
/**
* This method creates a tax rate.
*
* @param {CreateTaxRateDTO} data - The tax rate to be created.
* @param {Context} sharedContext - A context used to share resources, such as transaction manager, between the application and the module.
* @returns {Promise<TaxRateDTO>} The created tax rate.
*
* @example
* const taxRate = await taxModuleService.create({
* tax_region_id: "txreg_123",
* name: "Default rate",
* rate: 10,
* })
*/
create(data: CreateTaxRateDTO, sharedContext?: Context): Promise<TaxRateDTO>
/**
* This method updates an existing tax rate.
*
* @param {string} taxRateId - The tax rate's ID.
* @param {UpdateTaxRateDTO} data - The attributes to update in the tax rate.
* @param {Context} sharedContext - A context used to share resources, such as transaction manager, between the application and the module.
* @returns {Promise<TaxRateDTO>} The updated tax rate.
*
* @example
* const taxRate = await taxModuleService.update("txr_123", {
* rate: 10,
* })
*/
update(
taxRateId: string,
data: UpdateTaxRateDTO,
sharedContext?: Context
): Promise<TaxRateDTO>
/**
* This method updates existing tax rates.
*
* @param {string[]} taxRateIds - The IDs of tax rates to update.
* @param {UpdateTaxRateDTO} data - The attributes to update in the tax rate.
* @param {Context} sharedContext - A context used to share resources, such as transaction manager, between the application and the module.
* @returns {Promise<TaxRateDTO[]>} The updated tax rates.
*
* @example
* const taxRates = await taxModuleService.update(
* ["txr_123", "txr_321"],
* {
* rate: 10,
* }
* )
*/
update(
taxRateIds: string[],
data: UpdateTaxRateDTO,
sharedContext?: Context
): Promise<TaxRateDTO[]>
/**
* This method updates existing tax rates matching the specified filters.
*
* @param {FilterableTaxRateProps} selector - The filters specifying which tax rates to update.
* @param {UpdateTaxRateDTO} data - The attributes to update in the tax rate.
* @param {Context} sharedContext - A context used to share resources, such as transaction manager, between the application and the module.
* @returns {Promise<TaxRateDTO[]>} The updated tax rates.
*
* @example
* const taxRates = await taxModuleService.update(
* {
* id: ["txr_123", "txr_321"],
* },
* {
* rate: 10,
* }
* )
*/
update(
selector: FilterableTaxRateProps,
data: UpdateTaxRateDTO,
sharedContext?: Context
): Promise<TaxRateDTO[]>
/**
* This method updates or creates a tax rate if it doesn't exist.
*
* @param {UpsertTaxRateDTO} data - The attributes in the tax rate to be created or updated.
* @param {Context} sharedContext - A context used to share resources, such as transaction manager, between the application and the module.
* @returns {Promise<TaxRateDTO>} The created or updated tax rate.
*
* @example
* const taxRate = await taxModuleService.upsert({
* id: "txr_123",
* rate: 10,
* })
*/
upsert(data: UpsertTaxRateDTO, sharedContext?: Context): Promise<TaxRateDTO>
/**
* This method updates or creates tax rates if they don't exist.
*
* @param {UpsertTaxRateDTO[]} data - The attributes in the tax rates to be created or updated.
* @param {Context} sharedContext - A context used to share resources, such as transaction manager, between the application and the module.
* @returns {Promise<TaxRateDTO[]>} The created or updated tax rates.
*
* @example
* const taxRates = await taxModuleService.upsert([
* {
* id: "txr_123",
* rate: 10,
* },
* ])
*/
upsert(
data: UpsertTaxRateDTO[],
sharedContext?: Context
): Promise<TaxRateDTO[]>
/**
* This method deletes tax rates by their IDs.
*
* @param {string[]} taxRateIds - The IDs of tax rates to delete.
* @param {Context} sharedContext - A context used to share resources, such as transaction manager, between the application and the module.
* @returns {Promise<void>} Resolves when the tax rates are deleted successfully.
*
* @example
* await taxModuleService.delete(["txr_123", "txr_321"])
*/
delete(taxRateIds: string[], sharedContext?: Context): Promise<void>
/**
* This method deletes a tax rate by its ID.
*
* @param {string} taxRateId - The tax rate's ID.
* @param {Context} sharedContext - A context used to share resources, such as transaction manager, between the application and the module.
* @returns {Promise<void>} Resolves when the tax rate is deleted successfully.
*
* @example
* await taxModuleService.delete("txr_123")
*/
delete(taxRateId: string, sharedContext?: Context): Promise<void>
/**
* This method restores soft deleted tax rates by their IDs.
*
* @param {string[]} taxRateIds - The IDs of the tax rates.
* @param {RestoreReturn<TReturnableLinkableKeys>} config - Configurations determining which relations to restore along with each of the tax. You can pass to its `returnLinkableKeys`
* property any of the tax rate's relation attribute names, such as `rules`.
* @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, such as the ID of associated rules.
* The object's keys are the ID attribute names of the tax rate entity's relations, such as `rule_id`,
* and its value is an array of strings, each being the ID of the record associated with the tax rate through this relation,
* such as the IDs of associated rules.
*
* If there are no related records restored, the promise resolves to `void`.
*
* @example
* await taxModuleService.restore(["txr_123", "txr_321"])
*/
restore<TReturnableLinkableKeys extends string = string>(
taxRateIds: string[],
config?: RestoreReturn<TReturnableLinkableKeys>,
sharedContext?: Context
): Promise<Record<string, string[]> | void>
/**
* This method creates a tax region.
*
* @param {CreateTaxRegionDTO} data - The tax region to be created.
* @param {Context} sharedContext - A context used to share resources, such as transaction manager, between the application and the module.
* @returns {Promise<TaxRegionDTO>} The created tax region.
*
* @example
* const taxRegion = await taxModuleService.createTaxRegions({
* country_code: "us",
* })
*/
createTaxRegions(
data: CreateTaxRegionDTO,
sharedContext?: Context
): Promise<TaxRegionDTO>
/**
* This method creates tax regions.
*
* @param {CreateTaxRegionDTO[]} data - The tax regions to be created.
* @param {Context} sharedContext - A context used to share resources, such as transaction manager, between the application and the module.
* @returns {Promise<TaxRegionDTO[]>} The created tax regions.
*
* @example
* const taxRegions = await taxModuleService.createTaxRegions([
* {
* country_code: "us",
* },
* {
* country_code: "gb",
* },
* ])
*/
createTaxRegions(
data: CreateTaxRegionDTO[],
sharedContext?: Context
): Promise<TaxRegionDTO[]>
/**
* This method deletes tax regions by their IDs.
*
* @param {string[]} taxRegionIds - The IDs of the tax regions.
* @param {Context} sharedContext - A context used to share resources, such as transaction manager, between the application and the module.
* @returns {Promise<void>} Resolves when the tax regions are deleted.
*
* @example
* await taxModuleService.deleteTaxRegions([
* "txreg_123",
* "txreg_321",
* ])
*/
deleteTaxRegions(
taxRegionIds: string[],
sharedContext?: Context
): Promise<void>
/**
* This method deletes a tax region by its ID.
*
* @param {string} taxRegionId - The tax region's ID.
* @param {Context} sharedContext - A context used to share resources, such as transaction manager, between the application and the module.
* @returns {Promise<void>} Resolves when the tax region is successfully deleted.
*
* @example
* await taxModuleService.deleteTaxRegions("txreg_123")
*/
deleteTaxRegions(taxRegionId: string, sharedContext?: Context): Promise<void>
/**
* This method retrieves a paginated list of tax regions based on optional filters and configuration.
*
* @param {FilterableTaxRegionProps} filters - The filters to apply on the retrieved tax regions.
* @param {FindConfig<TaxRegionDTO>} config - The configurations determining how the tax region is retrieved. Its properties, such as `select` or `relations`, accept the
* attributes or relations associated with a tax region.
* @param {Context} sharedContext - A context used to share resources, such as transaction manager, between the application and the module.
* @returns {Promise<TaxRegionDTO[]>} The list of tax regions.
*
* @example
* To retrieve a list of tax regions using their IDs:
*
* ```ts
* const taxRegions = await taxModuleService.listTaxRegions({
* id: ["txreg_123", "txreg_321"],
* })
* ```
*
* To specify relations that should be retrieved within the tax region:
*
* ```ts
* const taxRegions = await taxModuleService.listTaxRegions(
* {
* id: ["txreg_123", "txreg_321"],
* },
* {
* relations: ["tax_rates"],
* }
* )
* ```
*
* By default, only the first `15` records are retrieved. You can control pagination by specifying the `skip` and `take` properties of the `config` parameter:
*
* ```ts
* const taxRegions = await taxModuleService.listTaxRegions(
* {
* id: ["txreg_123", "txreg_321"],
* },
* {
* relations: ["tax_rates"],
* take: 20,
* skip: 2,
* }
* )
* ```
*/
listTaxRegions(
filters?: FilterableTaxRegionProps,
config?: FindConfig<TaxRegionDTO>,
sharedContext?: Context
): Promise<TaxRegionDTO[]>
/**
* This method creates a tax rate rule.
*
* @param {CreateTaxRateRuleDTO} data - The tax rate rule to be created.
* @param {Context} sharedContext - A context used to share resources, such as transaction manager, between the application and the module.
* @returns {Promise<TaxRateRuleDTO>} The created tax rate rule.
*
* @example
* const taxRateRule = await taxModuleService.createTaxRateRules(
* {
* reference: "product_type",
* reference_id: "ptyp_123",
* tax_rate_id: "txr_123",
* }
* )
*/
createTaxRateRules(
data: CreateTaxRateRuleDTO,
sharedContext?: Context
): Promise<TaxRateRuleDTO>
/**
* This method creates tax rate rules.
*
* @param {CreateTaxRateRuleDTO[]} data - The tax rate rules to be created.
* @param {Context} sharedContext - A context used to share resources, such as transaction manager, between the application and the module.
* @returns {Promise<TaxRateRuleDTO[]>} The created tax rate rules.
*
* @example
* const taxRateRules =
* await taxModuleService.createTaxRateRules([
* {
* reference: "product_type",
* reference_id: "ptyp_123",
* tax_rate_id: "txr_123",
* },
* {
* reference: "product",
* reference_id: "prod_123",
* tax_rate_id: "txr_321",
* },
* ])
*/
createTaxRateRules(
data: CreateTaxRateRuleDTO[],
sharedContext?: Context
): Promise<TaxRateRuleDTO[]>
/**
* This method deletes a tax rate rule by its ID.
*
* @param {string} taxRateRuleId - The tax rate rule's ID.
* @param {Context} sharedContext - A context used to share resources, such as transaction manager, between the application and the module.
* @returns {Promise<void>} Resolves when the tax rate rule is deleted successfully.
*
* @example
* await taxModuleService.deleteTaxRateRules("txrule_123")
*/
deleteTaxRateRules(
taxRateRuleId: string,
sharedContext?: Context
): Promise<void>
/**
* This method deletes tax rate rules by their IDs.
*
* @param {string[]} taxRateRuleIds - The tax rate rules' IDs.
* @param {Context} sharedContext - A context used to share resources, such as transaction manager, between the application and the module.
* @returns {Promise<void>} Resolves when the tax rate rules are deleted successfully.
*
* @example
* await taxModuleService.deleteTaxRateRules([
* "txrule_123",
* "txrule_321",
* ])
*/
deleteTaxRateRules(
taxRateRuleIds: string[],
sharedContext?: Context
): Promise<void>
/**
* This method retrieves a paginated list of tax rate rules based on optional filters and configuration.
*
* @param {FilterableTaxRateRuleProps} filters - The filters to apply on the retrieved tax rate rules.
* @param {FindConfig<TaxRateRuleDTO>} config - The configurations determining how the tax rate rule is retrieved. Its properties, such as `select` or `relations`, accept the
* attributes or relations associated with a tax rate rule.
* @param {Context} sharedContext - A context used to share resources, such as transaction manager, between the application and the module.
* @returns {Promise<TaxRateRuleDTO[]>} The list of tax rate rules.
*
* @example
* To retrieve a list of tax rate rules using their associated tax rate's ID:
*
* ```ts
* const taxRateRules = await taxModuleService.listTaxRateRules({
* tax_rate_id: ["txr_123", "txr_321"],
* })
* ```
*
* To specify relations that should be retrieved within the tax rate rule:
*
* ```ts
* const taxRateRules = await taxModuleService.listTaxRateRules(
* {
* tax_rate_id: ["txr_123", "txr_321"],
* },
* {
* relations: ["tax_rate"],
* }
* )
* ```
*
* By default, only the first `15` records are retrieved. You can control pagination by specifying the `skip` and `take` properties of the `config` parameter:
*
* ```ts
* const taxRateRules = await taxModuleService.listTaxRateRules(
* {
* tax_rate_id: ["txr_123", "txr_321"],
* },
* {
* relations: ["tax_rate"],
* take: 20,
* skip: 2,
* }
* )
* ```
*/
listTaxRateRules(
filters?: FilterableTaxRateRuleProps,
config?: FindConfig<TaxRateRuleDTO>,
sharedContext?: Context
): Promise<TaxRateRuleDTO[]>
/**
* This method retrieves tax lines for taxable items and shipping methods in a cart.
*
* Learn more in [this guide](https://docs.medusajs.com/experimental/tax/tax-calculation-with-provider/).
*
* @param {(TaxableItemDTO | TaxableShippingDTO)[]} items - The items and shipping methods to retrieve their tax lines.
* @param {TaxCalculationContext} calculationContext - The context to pass to the underlying tax provider. It provides more
* details that are useful to provide accurate tax lines.
* @param {Context} sharedContext - A context used to share resources, such as transaction manager, between the application and the module.
* @returns {Promise<(ItemTaxLineDTO | ShippingTaxLineDTO)[]>} The item and shipping methods' tax lines.
*
* @example
* const taxLines = await taxModuleService.getTaxLines(
* [
* {
* id: "cali_123",
* product_id: "prod_123",
* unit_price: 1000,
* quantity: 1,
* },
* {
* id: "casm_123",
* shipping_option_id: "so_123",
* unit_price: 2000,
* },
* ],
* {
* address: {
* country_code: "us",
* },
* }
* )
*/
getTaxLines(
items: (TaxableItemDTO | TaxableShippingDTO)[],
calculationContext: TaxCalculationContext,
sharedContext?: Context
): Promise<(ItemTaxLineDTO | ShippingTaxLineDTO)[]>
/**
* This method soft deletes tax raes by their IDs.
*
* @param {string[]} taxRateIds - The IDs of the tax rates.
* @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, such as the ID of the associated rules.
* The object's keys are the ID attribute names of the tax rate entity's relations, such as `rule_id`, and its value is an array of strings, each being the ID of a record associated
* with the tax rate through this relation, such as the IDs of associated rules.
*
* If there are no related records, the promise resolves to `void`.
*
* @example
* await taxModuleService.softDelete(["txr_123", "txr_321"])
*/
softDelete<TReturnableLinkableKeys extends string = string>(
taxRateIds: string[],
config?: SoftDeleteReturn<TReturnableLinkableKeys>,
sharedContext?: Context
): Promise<Record<string, string[]> | void>
/**
* This method soft deletes tax regions by their IDs.
*
* @param {string[]} taxRegionIds - The IDs of the tax regions.
* @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, such as the ID of the associated tax rates.
* The object's keys are the ID attribute names of the tax region entity's relations, such as `tax_rate_id`, and its value is an array of strings, each being the ID of a record associated
* with the tax region through this relation, such as the IDs of associated tax rates.
*
* If there are no related records, the promise resolves to `void`.
*
* @example
* await taxModuleService.softDeleteTaxRegions([
* "txreg_123",
* "txreg_321",
* ])
*/
softDeleteTaxRegions<TReturnableLinkableKeys extends string = string>(
taxRegionIds: string[],
config?: SoftDeleteReturn<TReturnableLinkableKeys>,
sharedContext?: Context
): Promise<Record<string, string[]> | void>
/**
* This method restores soft deleted tax regions by their IDs.
*
* @param {string[]} taxRegionIds - The IDs of the tax regions.
* @param {RestoreReturn<TReturnableLinkableKeys>} config - Configurations determining which relations to restore along with each of the tax. You can pass to its `returnLinkableKeys`
* property any of the tax region's relation attribute names, such as `tax_rates`.
* @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, such as the ID of associated tax rates.
* The object's keys are the ID attribute names of the tax region entity's relations, such as `tax_rate_id`,
* and its value is an array of strings, each being the ID of the record associated with the tax region through this relation,
* such as the IDs of associated tax rates.
*
* If there are no related records restored, the promise resolves to `void`.
*
* @example
* await taxModuleService.restoreTaxRegions([
* "txreg_123",
* "txreg_321",
* ])
*/
restoreTaxRegions<TReturnableLinkableKeys extends string = string>(
taxRegionIds: string[],
config?: RestoreReturn<TReturnableLinkableKeys>,
sharedContext?: Context
): Promise<Record<string, string[]> | void>
/**
* This method soft deletes tax rate rules by their IDs.
*
* @param {string[]} taxRateRuleIds - The IDs of the tax rate rules.
* @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 taxModuleService.softDeleteTaxRateRules([
* "txrule_123",
* "txrule_321",
* ])
*/
softDeleteTaxRateRules<TReturnableLinkableKeys extends string = string>(
taxRateRuleIds: string[],
config?: SoftDeleteReturn<TReturnableLinkableKeys>,
sharedContext?: Context
): Promise<Record<string, string[]> | void>
/**
* This method restores soft deleted tax rate rules by their IDs.
*
* @param {string[]} taxRateRuleIds - The IDs of the tax rate rules.
* @param {RestoreReturn<TReturnableLinkableKeys>} config - Configurations determining which relations to restore along with each of the tax. You can pass to its `returnLinkableKeys`
* property any of the tax rate rule's relation attribute names.
* @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 taxModuleService.restoreTaxRateRules([
* "txrule_123",
* "txrule_321",
* ])
*/
restoreTaxRateRules<TReturnableLinkableKeys extends string = string>(
taxRateRuleIds: string[],
config?: RestoreReturn<TReturnableLinkableKeys>,