bb87db8342
This PR includes documentation that preps for v2 docs (but doesn't introduce new docs). _Note: The number of file changes in the PR is due to find-and-replace within the `references` which is unavoidable. Let me know if I should move it to another PR._ ## Changes - Change Medusa version in base OAS used for v2. - Fix to docblock generator related to not catching all path parameters. - Added typedoc plugin that generates ER Diagrams, which will be used specifically for data model references in commerce modules. - Changed OAS tool to output references in `www/apps/api-reference/specs-v2` directory when the `--v2` option is used. - Added a version switcher to the API reference to switch between V1 and V2. This switcher is enabled by an environment variable, so it won't be visible/usable at the moment. - Upgraded docusaurus to v3.0.1 - Added new Vale rules to ensure correct spelling of Medusa Admin and module names. - Added new components to the `docs-ui` package that will be used in future documentation changes.
227 lines
16 KiB
Plaintext
227 lines
16 KiB
Plaintext
---
|
|
displayed_sidebar: servicesSidebar
|
|
---
|
|
|
|
import TypeList from "@site/src/components/TypeList"
|
|
|
|
# TaxProviderService
|
|
|
|
Finds tax providers and assists in tax related operations.
|
|
|
|
## constructor
|
|
|
|
### Parameters
|
|
|
|
<TypeList types={[{"name":"container","type":"AwilixContainer<any>","description":"","optional":false,"defaultValue":"","expandable":false,"children":[]}]} sectionTitle="new TaxProviderService"/>
|
|
|
|
___
|
|
|
|
## Properties
|
|
|
|
<TypeList types={[{"name":"manager_","type":"`EntityManager`","description":"","optional":false,"defaultValue":"","expandable":false,"children":[]},{"name":"transactionManager_","type":"`undefined` \\| `EntityManager`","description":"","optional":false,"defaultValue":"","expandable":false,"children":[]},{"name":"__container__","type":"`any`","description":"","optional":false,"defaultValue":"","expandable":false,"children":[]},{"name":"container_","type":"AwilixContainer<any>","description":"","optional":false,"defaultValue":"","expandable":false,"children":[]},{"name":"cacheService_","type":"[ICacheService](../../types/CacheTypes/interfaces/types.CacheTypes.ICacheService.mdx)","description":"","optional":false,"defaultValue":"","expandable":false,"children":[]},{"name":"taxRateService_","type":"[TaxRateService](services.TaxRateService.mdx)","description":"","optional":false,"defaultValue":"","expandable":false,"children":[]},{"name":"taxLineRepo_","type":"Repository<[LineItemTaxLine](../../entities/classes/entities.LineItemTaxLine.mdx)> & `object`","description":"","optional":false,"defaultValue":"","expandable":false,"children":[]},{"name":"smTaxLineRepo_","type":"Repository<[ShippingMethodTaxLine](../../entities/classes/entities.ShippingMethodTaxLine.mdx)> & `object`","description":"","optional":false,"defaultValue":"","expandable":false,"children":[]},{"name":"taxProviderRepo_","type":"Repository<[TaxProvider](../../entities/classes/entities.TaxProvider.mdx)>","description":"","optional":false,"defaultValue":"","expandable":false,"children":[]},{"name":"eventBus_","type":"[IEventBusService](../../types/EventBusTypes/interfaces/types.EventBusTypes.IEventBusService.mdx)","description":"","optional":false,"defaultValue":"","expandable":false,"children":[]},{"name":"__configModule__","type":"`Record<string, unknown>`","description":"","optional":true,"defaultValue":"","expandable":false,"children":[]},{"name":"__moduleDeclaration__","type":"`Record<string, unknown>`","description":"","optional":true,"defaultValue":"","expandable":false,"children":[]}]} sectionTitle="TaxProviderService"/>
|
|
|
|
___
|
|
|
|
## Accessors
|
|
|
|
### activeManager\_
|
|
|
|
#### Returns
|
|
|
|
<TypeList types={[{"name":"EntityManager","type":"`EntityManager`","optional":false,"defaultValue":"","description":"","expandable":false,"children":[]}]} sectionTitle="activeManager_"/>
|
|
|
|
___
|
|
|
|
## Methods
|
|
|
|
### withTransaction
|
|
|
|
#### Parameters
|
|
|
|
<TypeList types={[{"name":"transactionManager","type":"`EntityManager`","description":"","optional":true,"defaultValue":"","expandable":false,"children":[]}]} sectionTitle="withTransaction"/>
|
|
|
|
#### Returns
|
|
|
|
<TypeList types={[{"name":"this","type":"`this`","optional":false,"defaultValue":"","description":"","expandable":false,"children":[]}]} sectionTitle="withTransaction"/>
|
|
|
|
### shouldRetryTransaction\_
|
|
|
|
#### Parameters
|
|
|
|
<TypeList types={[{"name":"err","type":"`Record<string, unknown>` \\| `object`","description":"","optional":false,"defaultValue":"","expandable":false,"children":[]}]} sectionTitle="shouldRetryTransaction_"/>
|
|
|
|
#### Returns
|
|
|
|
<TypeList types={[{"name":"boolean","type":"`boolean`","optional":false,"defaultValue":"","description":"","expandable":false,"children":[]}]} sectionTitle="shouldRetryTransaction_"/>
|
|
|
|
### atomicPhase\_
|
|
|
|
Wraps some work within a transactional block. If the service already has
|
|
a transaction manager attached this will be reused, otherwise a new
|
|
transaction manager is created.
|
|
|
|
#### Type Parameters
|
|
|
|
<TypeList types={[{"name":"TResult","type":"`object`","description":"","optional":false,"defaultValue":"","expandable":false,"children":[]},{"name":"TError","type":"`object`","description":"","optional":false,"defaultValue":"","expandable":false,"children":[]}]} sectionTitle="atomicPhase_"/>
|
|
|
|
#### Parameters
|
|
|
|
<TypeList types={[{"name":"work","type":"(`transactionManager`: `EntityManager`) => Promise<TResult>","description":"the transactional work to be done","optional":false,"defaultValue":"","expandable":false,"children":[]},{"name":"isolationOrErrorHandler","type":"`IsolationLevel` \\| (`error`: TError) => Promise<void \\| TResult>","description":"the isolation level to be used for the work.","optional":true,"defaultValue":"","expandable":false,"children":[]},{"name":"maybeErrorHandlerOrDontFail","type":"(`error`: TError) => Promise<void \\| TResult>","description":"Potential error handler","optional":true,"defaultValue":"","expandable":false,"children":[]}]} sectionTitle="atomicPhase_"/>
|
|
|
|
#### Returns
|
|
|
|
<TypeList types={[{"name":"Promise","type":"Promise<TResult>","optional":false,"defaultValue":"","description":"the result of the transactional work","expandable":false,"children":[]}]} sectionTitle="atomicPhase_"/>
|
|
|
|
### list
|
|
|
|
#### Returns
|
|
|
|
<TypeList types={[{"name":"Promise","type":"Promise<[TaxProvider](../../entities/classes/entities.TaxProvider.mdx)[]>","optional":false,"defaultValue":"","description":"","expandable":false,"children":[]}]} sectionTitle="list"/>
|
|
|
|
### retrieveProvider
|
|
|
|
Retrieves the relevant tax provider for the given region.
|
|
|
|
#### Parameters
|
|
|
|
<TypeList types={[{"name":"region","type":"[Region](../../entities/classes/entities.Region.mdx)","description":"the region to get tax provider for.","optional":false,"defaultValue":"","expandable":false,"children":[]}]} sectionTitle="retrieveProvider"/>
|
|
|
|
#### Returns
|
|
|
|
<TypeList types={[{"name":"ITaxService","type":"`object`","description":"## Overview\n\nA tax provider is used to retrieve the tax lines in a cart. The Medusa backend provides a default `system` provider. You can create your own tax provider,\neither in a plugin or directly in your Medusa backend, then use it in any region.\n\nA tax provider class is defined in a TypeScript or JavaScript file under the `src/services` directory and the class must extend the\n`AbstractTaxService` class imported from `@medusajs/medusa`. The file's name is the tax provider's class name as a slug and without the word `Service`.\n\nFor example, you can create the file `src/services/my-tax.ts` with the following content:\n\n```ts title=\"src/services/my-tax.ts\"\nimport {\n AbstractTaxService,\n ItemTaxCalculationLine,\n ShippingTaxCalculationLine,\n TaxCalculationContext,\n} from \"@medusajs/medusa\"\nimport {\n ProviderTaxLine,\n} from \"@medusajs/medusa/dist/types/tax-service\"\n\nclass MyTaxService extends AbstractTaxService {\n async getTaxLines(\n itemLines: ItemTaxCalculationLine[],\n shippingLines: ShippingTaxCalculationLine[],\n context: TaxCalculationContext):\n Promise<ProviderTaxLine[]> {\n throw new Error(\"Method not implemented.\")\n }\n}\n\nexport default MyTaxService\n```\n\n---\n\n## Identifier Property\n\nThe `TaxProvider` entity has 2 properties: `identifier` and `is_installed`. The `identifier` property in the tax provider service is used when the tax provider is added to the database.\n\nThe value of this property is also used to reference the tax provider throughout Medusa. For example, it is used to [change the tax provider](https://docs.medusajs.com/modules/taxes/admin/manage-tax-settings#change-tax-provider-of-a-region) to a region.\n\n```ts title=\"src/services/my-tax.ts\"\nclass MyTaxService extends AbstractTaxService {\n static identifier = \"my-tax\"\n // ...\n}\n```\n\n---","optional":false,"defaultValue":"","expandable":false,"children":[]}]} sectionTitle="retrieveProvider"/>
|
|
|
|
### clearLineItemsTaxLines
|
|
|
|
#### Parameters
|
|
|
|
<TypeList types={[{"name":"itemIds","type":"`string`[]","description":"","optional":false,"defaultValue":"","expandable":false,"children":[]}]} sectionTitle="clearLineItemsTaxLines"/>
|
|
|
|
#### Returns
|
|
|
|
<TypeList types={[{"name":"Promise","type":"Promise<void>","optional":false,"defaultValue":"","description":"","expandable":false,"children":[]}]} sectionTitle="clearLineItemsTaxLines"/>
|
|
|
|
### clearTaxLines
|
|
|
|
#### Parameters
|
|
|
|
<TypeList types={[{"name":"cartId","type":"`string`","description":"","optional":false,"defaultValue":"","expandable":false,"children":[]}]} sectionTitle="clearTaxLines"/>
|
|
|
|
#### Returns
|
|
|
|
<TypeList types={[{"name":"Promise","type":"Promise<void>","optional":false,"defaultValue":"","description":"","expandable":false,"children":[]}]} sectionTitle="clearTaxLines"/>
|
|
|
|
### createTaxLines
|
|
|
|
Persists the tax lines relevant for an order to the database.
|
|
|
|
#### Parameters
|
|
|
|
<TypeList types={[{"name":"cartOrLineItems","type":"[LineItem](../../entities/classes/entities.LineItem.mdx)[] \\| [Cart](../../entities/classes/entities.Cart.mdx)","description":"the cart or line items to create tax lines for","optional":false,"defaultValue":"","expandable":false,"children":[]},{"name":"calculationContext","type":"[TaxCalculationContext](../../medusa/types/medusa.TaxCalculationContext.mdx)","description":"the calculation context to get tax lines by","optional":false,"defaultValue":"","expandable":false,"children":[]}]} sectionTitle="createTaxLines"/>
|
|
|
|
#### Returns
|
|
|
|
<TypeList types={[{"name":"Promise","type":"Promise<([LineItemTaxLine](../../entities/classes/entities.LineItemTaxLine.mdx) \\| [ShippingMethodTaxLine](../../entities/classes/entities.ShippingMethodTaxLine.mdx))[]>","optional":false,"defaultValue":"","description":"the newly created tax lines","expandable":false,"children":[]}]} sectionTitle="createTaxLines"/>
|
|
|
|
### createShippingTaxLines
|
|
|
|
Persists the tax lines relevant for a shipping method to the database. Used
|
|
for return shipping methods.
|
|
|
|
#### Parameters
|
|
|
|
<TypeList types={[{"name":"shippingMethod","type":"[ShippingMethod](../../entities/classes/entities.ShippingMethod.mdx)","description":"the shipping method to create tax lines for","optional":false,"defaultValue":"","expandable":false,"children":[]},{"name":"calculationContext","type":"[TaxCalculationContext](../../medusa/types/medusa.TaxCalculationContext.mdx)","description":"the calculation context to get tax lines by","optional":false,"defaultValue":"","expandable":false,"children":[]}]} sectionTitle="createShippingTaxLines"/>
|
|
|
|
#### Returns
|
|
|
|
<TypeList types={[{"name":"Promise","type":"Promise<([LineItemTaxLine](../../entities/classes/entities.LineItemTaxLine.mdx) \\| [ShippingMethodTaxLine](../../entities/classes/entities.ShippingMethodTaxLine.mdx))[]>","optional":false,"defaultValue":"","description":"the newly created tax lines","expandable":false,"children":[]}]} sectionTitle="createShippingTaxLines"/>
|
|
|
|
### getShippingTaxLines
|
|
|
|
Gets the relevant tax lines for a shipping method. Note: this method
|
|
doesn't persist the tax lines. Use createShippingTaxLines if you wish to
|
|
persist the tax lines to the DB layer.
|
|
|
|
#### Parameters
|
|
|
|
<TypeList types={[{"name":"shippingMethod","type":"[ShippingMethod](../../entities/classes/entities.ShippingMethod.mdx)","description":"the shipping method to get tax lines for","optional":false,"defaultValue":"","expandable":false,"children":[]},{"name":"calculationContext","type":"[TaxCalculationContext](../../medusa/types/medusa.TaxCalculationContext.mdx)","description":"the calculation context to get tax lines by","optional":false,"defaultValue":"","expandable":false,"children":[]}]} sectionTitle="getShippingTaxLines"/>
|
|
|
|
#### Returns
|
|
|
|
<TypeList types={[{"name":"Promise","type":"Promise<[ShippingMethodTaxLine](../../entities/classes/entities.ShippingMethodTaxLine.mdx)[]>","optional":false,"defaultValue":"","description":"the computed tax lines","expandable":false,"children":[]}]} sectionTitle="getShippingTaxLines"/>
|
|
|
|
### getTaxLines
|
|
|
|
Gets the relevant tax lines for an order or cart. If an order is provided
|
|
the order's tax lines will be returned. If a cart is provided the tax lines
|
|
will be computed from the tax rules and potentially a 3rd party tax plugin.
|
|
Note: this method doesn't persist the tax lines. Use createTaxLines if you
|
|
wish to persist the tax lines to the DB layer.
|
|
|
|
#### Parameters
|
|
|
|
<TypeList types={[{"name":"lineItems","type":"[LineItem](../../entities/classes/entities.LineItem.mdx)[]","description":"the cart or order to get tax lines for","optional":false,"defaultValue":"","expandable":false,"children":[]},{"name":"calculationContext","type":"[TaxCalculationContext](../../medusa/types/medusa.TaxCalculationContext.mdx)","description":"the calculation context to get tax lines by","optional":false,"defaultValue":"","expandable":false,"children":[]}]} sectionTitle="getTaxLines"/>
|
|
|
|
#### Returns
|
|
|
|
<TypeList types={[{"name":"Promise","type":"Promise<([LineItemTaxLine](../../entities/classes/entities.LineItemTaxLine.mdx) \\| [ShippingMethodTaxLine](../../entities/classes/entities.ShippingMethodTaxLine.mdx))[]>","optional":false,"defaultValue":"","description":"the computed tax lines","expandable":false,"children":[]}]} sectionTitle="getTaxLines"/>
|
|
|
|
### getTaxLinesMap
|
|
|
|
Return a map of tax lines for line items and shipping methods
|
|
|
|
#### Parameters
|
|
|
|
<TypeList types={[{"name":"items","type":"[LineItem](../../entities/classes/entities.LineItem.mdx)[]","description":"","optional":false,"defaultValue":"","expandable":false,"children":[]},{"name":"calculationContext","type":"[TaxCalculationContext](../../medusa/types/medusa.TaxCalculationContext.mdx)","description":"","optional":false,"defaultValue":"","expandable":false,"children":[]}]} sectionTitle="getTaxLinesMap"/>
|
|
|
|
#### Returns
|
|
|
|
<TypeList types={[{"name":"Promise","type":"Promise<TaxLinesMaps>","optional":false,"defaultValue":"","description":"Return a map of tax lines for line items and shipping methods","expandable":false,"children":[]}]} sectionTitle="getTaxLinesMap"/>
|
|
|
|
### getRegionRatesForShipping
|
|
|
|
Gets the tax rates configured for a shipping option. The rates are cached
|
|
between calls.
|
|
|
|
#### Parameters
|
|
|
|
<TypeList types={[{"name":"optionId","type":"`string`","description":"the option id of the shipping method.","optional":false,"defaultValue":"","expandable":false,"children":[]},{"name":"regionDetails","type":"`RegionDetails`","description":"the region to get configured rates for.","optional":false,"defaultValue":"","expandable":false,"children":[]}]} sectionTitle="getRegionRatesForShipping"/>
|
|
|
|
#### Returns
|
|
|
|
<TypeList types={[{"name":"Promise","type":"Promise<[TaxServiceRate](../../medusa/types/medusa.TaxServiceRate.mdx)[]>","optional":false,"defaultValue":"","description":"the tax rates configured for the shipping option.","expandable":false,"children":[]}]} sectionTitle="getRegionRatesForShipping"/>
|
|
|
|
### getRegionRatesForProduct
|
|
|
|
Gets the tax rates configured for a product. The rates are cached between
|
|
calls.
|
|
|
|
#### Parameters
|
|
|
|
<TypeList types={[{"name":"productIds","type":"`string` \\| `string`[]","description":"","optional":false,"defaultValue":"","expandable":false,"children":[]},{"name":"region","type":"`RegionDetails`","description":"the region to get configured rates for.","optional":false,"defaultValue":"","expandable":false,"children":[]}]} sectionTitle="getRegionRatesForProduct"/>
|
|
|
|
#### Returns
|
|
|
|
<TypeList types={[{"name":"Promise","type":"Promise<Map<string, [TaxServiceRate](../../medusa/types/medusa.TaxServiceRate.mdx)[]>>","optional":false,"defaultValue":"","description":"the tax rates configured for the shipping option. A map by product id","expandable":false,"children":[]}]} sectionTitle="getRegionRatesForProduct"/>
|
|
|
|
### getCacheKey
|
|
|
|
The cache key to get cache hits by.
|
|
|
|
#### Parameters
|
|
|
|
<TypeList types={[{"name":"id","type":"`string`","description":"the entity id to cache","optional":false,"defaultValue":"","expandable":false,"children":[]},{"name":"regionId","type":"`string`","description":"the region id to cache","optional":false,"defaultValue":"","expandable":false,"children":[]}]} sectionTitle="getCacheKey"/>
|
|
|
|
#### Returns
|
|
|
|
<TypeList types={[{"name":"string","type":"`string`","optional":false,"defaultValue":"","description":"the cache key to use for the id set","expandable":false,"children":[]}]} sectionTitle="getCacheKey"/>
|
|
|
|
### registerInstalledProviders
|
|
|
|
#### Parameters
|
|
|
|
<TypeList types={[{"name":"providers","type":"`string`[]","description":"","optional":false,"defaultValue":"","expandable":false,"children":[]}]} sectionTitle="registerInstalledProviders"/>
|
|
|
|
#### Returns
|
|
|
|
<TypeList types={[{"name":"Promise","type":"Promise<void>","optional":false,"defaultValue":"","description":"","expandable":false,"children":[]}]} sectionTitle="registerInstalledProviders"/>
|