diff --git a/www/apps/resources/references/auth_provider/classes/auth_provider.AbstractAuthModuleProvider/page.mdx b/www/apps/resources/references/auth_provider/classes/auth_provider.AbstractAuthModuleProvider/page.mdx index dd090247ab..f7e6284594 100644 --- a/www/apps/resources/references/auth_provider/classes/auth_provider.AbstractAuthModuleProvider/page.mdx +++ b/www/apps/resources/references/auth_provider/classes/auth_provider.AbstractAuthModuleProvider/page.mdx @@ -15,6 +15,7 @@ In this document, you’ll learn how to create an auth provider module and the m Start by creating a new directory for your module provider. If you're creating the module provider in a Medusa application, create it under the `src/modules` directory. For example, `src/modules/my-auth`. + If you're creating the module provider in a plugin, create it under the `src/providers` directory. For example, `src/providers/my-auth`. diff --git a/www/apps/resources/references/file/classes/file.AbstractFileProviderService/page.mdx b/www/apps/resources/references/file/classes/file.AbstractFileProviderService/page.mdx index e4842f9f8b..c68a6ebcf3 100644 --- a/www/apps/resources/references/file/classes/file.AbstractFileProviderService/page.mdx +++ b/www/apps/resources/references/file/classes/file.AbstractFileProviderService/page.mdx @@ -15,6 +15,7 @@ In this document, you’ll learn how to create a file provider module and the me Start by creating a new directory for your module provider. If you're creating the module provider in a Medusa application, create it under the `src/modules` directory. For example, `src/modules/my-file`. + If you're creating the module provider in a plugin, create it under the `src/providers` directory. For example, `src/providers/my-file`. diff --git a/www/apps/resources/references/fulfillment_provider/classes/fulfillment_provider.AbstractFulfillmentProviderService/page.mdx b/www/apps/resources/references/fulfillment_provider/classes/fulfillment_provider.AbstractFulfillmentProviderService/page.mdx index 09bc710771..246c985446 100644 --- a/www/apps/resources/references/fulfillment_provider/classes/fulfillment_provider.AbstractFulfillmentProviderService/page.mdx +++ b/www/apps/resources/references/fulfillment_provider/classes/fulfillment_provider.AbstractFulfillmentProviderService/page.mdx @@ -23,6 +23,7 @@ For example, when the merchant creates a fulfillment for an order, the Fulfillme Start by creating a new directory for your module provider. If you're creating the module provider in a Medusa application, create it under the `src/modules` directory. For example, `src/modules/my-fulfillment`. + If you're creating the module provider in a plugin, create it under the `src/providers` directory. For example, `src/providers/my-fulfillment`. diff --git a/www/apps/resources/references/notification/classes/notification.AbstractNotificationProviderService/page.mdx b/www/apps/resources/references/notification/classes/notification.AbstractNotificationProviderService/page.mdx index 222fac8316..d614ba3937 100644 --- a/www/apps/resources/references/notification/classes/notification.AbstractNotificationProviderService/page.mdx +++ b/www/apps/resources/references/notification/classes/notification.AbstractNotificationProviderService/page.mdx @@ -15,6 +15,7 @@ In this document, you’ll learn how to create a notification provider module an Start by creating a new directory for your module provider. If you're creating the module provider in a Medusa application, create it under the `src/modules` directory. For example, `src/modules/my-notification`. + If you're creating the module provider in a plugin, create it under the `src/providers` directory. For example, `src/providers/my-notification`. diff --git a/www/apps/resources/references/payment_provider/classes/payment_provider.AbstractPaymentProvider/page.mdx b/www/apps/resources/references/payment_provider/classes/payment_provider.AbstractPaymentProvider/page.mdx index 9e1d9a2e0d..b8b4235783 100644 --- a/www/apps/resources/references/payment_provider/classes/payment_provider.AbstractPaymentProvider/page.mdx +++ b/www/apps/resources/references/payment_provider/classes/payment_provider.AbstractPaymentProvider/page.mdx @@ -23,6 +23,7 @@ For example, when the merchant captures an order's payment, the Payment Module u Start by creating a new directory for your module provider. If you're creating the module provider in a Medusa application, create it under the `src/modules` directory. For example, `src/modules/my-payment`. + If you're creating the module provider in a plugin, create it under the `src/providers` directory. For example, `src/providers/my-payment`. diff --git a/www/apps/resources/references/tax_provider/interfaces/tax_provider.ITaxProvider/page.mdx b/www/apps/resources/references/tax_provider/interfaces/tax_provider.ITaxProvider/page.mdx index 0e0db73344..ebe60da903 100644 --- a/www/apps/resources/references/tax_provider/interfaces/tax_provider.ITaxProvider/page.mdx +++ b/www/apps/resources/references/tax_provider/interfaces/tax_provider.ITaxProvider/page.mdx @@ -8,55 +8,70 @@ import { TypeList } from "docs-ui" In this document, you’ll learn how to create a tax provider to use with the Tax Module, and the methods to implement. +--- + ## 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. +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 module provider, or directly in your Medusa application's codebase, then use it in any tax region. --- -## How to Create a Tax Provider +## Understanding Tax Provider Implementation -A tax provider class is defined in a TypeScript or JavaScript file. The class must implement the -`ITaxProvider` interface imported from `@medusajs/framework/types`. +The Tax Module Provider handles calculating taxes with a third-party provirder. However, it's not responsible for managing tax concepts within Medusa, such as creating a tax region. The Tax Module uses your tax provider within core operations. -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, during checkout, the tax provider of the tax region that the customer is in is used to calculate the tax for the cart and order. So, you only have to implement the third-party tax calculation logic in your tax provider. -For example: +--- -```ts title="src/services/my-tax.ts" +## 1. Create Module Provider Directory + +Start by creating a new directory for your module provider. + +If you're creating the module provider in a Medusa application, create it under the `src/modules` directory. For example, `src/modules/my-tax`. + +If you're creating the module provider in a plugin, create it under the `src/providers` directory. For example, `src/providers/my-tax`. + + + +The rest of this guide always uses the `src/modules/my-tax` directory as an example. + + + +--- + +## 2. Create the Tax Provider Service + +Create the file `src/modules/my-tax/service.ts` that holds the module's main service. It must extend the `ITaxProvider` class imported from `@medusajs/framework/types`: + +```ts title="src/modules/my-tax/service.ts" import { ITaxProvider } from "@medusajs/framework/types" export default class MyTaxProvider implements ITaxProvider { - // ... + // TODO implement methods } ``` ---- +### Identifier Property -## 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. +The `identifier` property in a tax provider is used when the tax provider is loaded by the Tax Module and 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" +```ts title="src/modules/my-tax/service.ts" export default class MyTaxProvider implements ITaxProvider { static identifier = "my-tax" // ... } ``` ---- +### constructor -## Constructor - -You can use the `constructor` of your tax provider to access the resources registered in the dependency container. +You can use the `constructor` of your tax provider to access the resources registered in the [Module Container](https://docs.medusajs.com/resources/medusa-container-resources#module-container-resources). 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. +Additionally, if you’re creating your tax provider as a plugin or a module provider to be installed in any Medusa application and you want to access its options, you can access them in the second parameter of the constructor. For example: @@ -75,14 +90,13 @@ export default class MyTaxProvider implements ITaxProvider { --- -## getTaxLines +### getTaxLines -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 used to retrieve the tax lines of items and shipping methods. It's used during checkout +when the `getTaxLines` method of the Tax Module's main service is called for a tax +region that uses this tax provider. -This method is useful during checkout or when calculating the totals of orders or exchanges. - -### Example +#### Example An example of how this method is implemented in the `system` provider: @@ -127,10 +141,59 @@ export default class SystemTaxService implements ITaxProvider { } ``` -### Parameters +#### Parameters `","description":"Holds custom data in key-value pairs.","optional":false,"defaultValue":"","expandable":false,"children":[]},{"name":"tax_region_id","type":"`string`","description":"The ID of the associated tax region.","optional":false,"defaultValue":"","expandable":false,"children":[]},{"name":"is_combinable","type":"`boolean`","description":"Whether the tax rate should be combined with parent rates.\n\nLearn more [here](https://docs.medusajs.com/resources/commerce-modules/tax/tax-rates-and-rules#combinable-tax-rates).","optional":false,"defaultValue":"","expandable":false,"children":[]},{"name":"is_default","type":"`boolean`","description":"Whether the tax rate is the default rate for the region.","optional":false,"defaultValue":"","expandable":false,"children":[]},{"name":"created_at","type":"`string` \\| `Date`","description":"The creation date of the tax rate.","optional":false,"defaultValue":"","expandable":false,"children":[]},{"name":"updated_at","type":"`string` \\| `Date`","description":"The update date of the tax rate.","optional":false,"defaultValue":"","expandable":false,"children":[]},{"name":"deleted_at","type":"`null` \\| `Date`","description":"The deletion date of the tax rate.","optional":false,"defaultValue":"","expandable":false,"children":[]},{"name":"created_by","type":"`null` \\| `string`","description":"Who created the tax rate. For example, the ID of the user that created the tax rate.","optional":false,"defaultValue":"","expandable":false,"children":[]}]}]},{"name":"shippingLines","type":"[ShippingTaxCalculationLine](../../types/tax_provider.ShippingTaxCalculationLine/page.mdx)[]","description":"The shipping method lines to calculate taxes for.","optional":false,"defaultValue":"","expandable":false,"children":[{"name":"shipping_line","type":"[TaxableShippingDTO](../../../tax/interfaces/tax.TaxableShippingDTO/page.mdx)","description":"The shipping method to calculate taxes for.","optional":false,"defaultValue":"","expandable":false,"children":[{"name":"id","type":"`string`","description":"The ID of the taxable shipping.","optional":false,"defaultValue":"","expandable":false,"children":[]},{"name":"shipping_option_id","type":"`string`","description":"The associated shipping option's ID.","optional":false,"defaultValue":"","expandable":false,"children":[]},{"name":"unit_price","type":"[BigNumberInput](../../../tax/types/tax.BigNumberInput/page.mdx)","description":"The unit price of the taxable shipping.","optional":true,"defaultValue":"","expandable":false,"children":[]},{"name":"currency_code","type":"`string`","description":"The ISO 3 character currency code of the taxable shipping.","optional":true,"defaultValue":"","expandable":false,"children":[]}]},{"name":"rates","type":"[TaxRateDTO](../../../tax/interfaces/tax.TaxRateDTO/page.mdx)[]","description":"The rates applicable on the shipping method.","optional":false,"defaultValue":"","expandable":false,"children":[{"name":"id","type":"`string`","description":"The ID of the tax rate.","optional":false,"defaultValue":"","expandable":false,"children":[]},{"name":"rate","type":"`null` \\| `number`","description":"The rate to charge.","optional":false,"defaultValue":"","expandable":false,"children":[]},{"name":"code","type":"`null` \\| `string`","description":"The code the tax rate is identified by.","optional":false,"defaultValue":"","expandable":false,"children":[]},{"name":"name","type":"`string`","description":"The name of the Tax Rate.","optional":false,"defaultValue":"","expandable":false,"children":[]},{"name":"metadata","type":"`null` \\| `Record`","description":"Holds custom data in key-value pairs.","optional":false,"defaultValue":"","expandable":false,"children":[]},{"name":"tax_region_id","type":"`string`","description":"The ID of the associated tax region.","optional":false,"defaultValue":"","expandable":false,"children":[]},{"name":"is_combinable","type":"`boolean`","description":"Whether the tax rate should be combined with parent rates.\n\nLearn more [here](https://docs.medusajs.com/resources/commerce-modules/tax/tax-rates-and-rules#combinable-tax-rates).","optional":false,"defaultValue":"","expandable":false,"children":[]},{"name":"is_default","type":"`boolean`","description":"Whether the tax rate is the default rate for the region.","optional":false,"defaultValue":"","expandable":false,"children":[]},{"name":"created_at","type":"`string` \\| `Date`","description":"The creation date of the tax rate.","optional":false,"defaultValue":"","expandable":false,"children":[]},{"name":"updated_at","type":"`string` \\| `Date`","description":"The update date of the tax rate.","optional":false,"defaultValue":"","expandable":false,"children":[]},{"name":"deleted_at","type":"`null` \\| `Date`","description":"The deletion date of the tax rate.","optional":false,"defaultValue":"","expandable":false,"children":[]},{"name":"created_by","type":"`null` \\| `string`","description":"Who created the tax rate. For example, the ID of the user that created the tax rate.","optional":false,"defaultValue":"","expandable":false,"children":[]}]}]},{"name":"context","type":"[TaxCalculationContext](../../../tax/interfaces/tax.TaxCalculationContext/page.mdx)","description":"The context relevant and useful for the taxes calculation.","optional":false,"defaultValue":"","expandable":false,"children":[{"name":"address","type":"`object`","description":"The customer's address","optional":false,"defaultValue":"","expandable":false,"children":[{"name":"country_code","type":"`string`","description":"The ISO 2 character currency code.","optional":false,"defaultValue":"","expandable":false,"children":[]},{"name":"province_code","type":"`null` \\| `string`","description":"The province code.","optional":true,"defaultValue":"","expandable":false,"children":[]},{"name":"address_1","type":"`string`","description":"The first line of the address.","optional":true,"defaultValue":"","expandable":false,"children":[]},{"name":"address_2","type":"`null` \\| `string`","description":"The second line of the address","optional":true,"defaultValue":"","expandable":false,"children":[]},{"name":"city","type":"`string`","description":"The city.","optional":true,"defaultValue":"","expandable":false,"children":[]},{"name":"postal_code","type":"`string`","description":"The postal code.","optional":true,"defaultValue":"","expandable":false,"children":[]},{"name":"metadata","type":"`null` \\| `Record`","description":"Address metadata.","optional":true,"defaultValue":"","expandable":false,"children":[]}]},{"name":"customer","type":"`object`","description":"The customer's details.","optional":true,"defaultValue":"","expandable":false,"children":[{"name":"id","type":"`string`","description":"The ID of the customer.","optional":false,"defaultValue":"","expandable":false,"children":[]},{"name":"email","type":"`string`","description":"The email of the customer.","optional":false,"defaultValue":"","expandable":false,"children":[]},{"name":"customer_groups","type":"`string`[]","description":"The groups that the customer belongs to.","optional":false,"defaultValue":"","expandable":false,"children":[]},{"name":"metadata","type":"`null` \\| `Record`","description":"Customer metadata.","optional":true,"defaultValue":"","expandable":false,"children":[]}]},{"name":"is_return","type":"`boolean`","description":"Whether the tax lines are calculated for an order return.","optional":true,"defaultValue":"","expandable":false,"children":[]}]}]} expandUrl="https://docs.medusajs.com/learn/fundamentals/data-models/manage-relationships#retrieve-records-of-relation" sectionTitle="getTaxLines"/> -### Returns +#### Returns + +--- + +## 3. Create Module Definition File + +Create the file `src/modules/my-tax/index.ts` with the following content: + +```ts title="src/modules/my-tax/index.ts" +import MyTaxProvider from "./service" +import { + ModuleProvider, + Modules +} from "@medusajs/framework/utils" + +export default ModuleProvider(Modules.TAX, { + services: [MyTaxProvider], +}) +``` + +This exports the module's definition, indicating that the `MyTaxProvider` is the module's service. + +--- + +## 4. Use Module + +To use your Tax Module Provider, add it to the `providers` array of the Tax Module in `medusa-config.ts`: + +```ts title="medusa-config.ts" +module.exports = defineConfig({ + // ... + modules: [ + { + resolve: "@medusajs/medusa/tax", + options: { + providers: [ + { + // if module provider is in a plugin, use `plugin-name/providers/my-tax` + resolve: "./src/modules/my-tax", + id: "my-tax", + options: { + // provider options... + }, + }, + ], + }, + }, + ] +}) +``` diff --git a/www/utils/generated/typedoc-json-output/tax-provider.json b/www/utils/generated/typedoc-json-output/tax-provider.json index 3c92c6951f..179b2fc87b 100644 --- a/www/utils/generated/typedoc-json-output/tax-provider.json +++ b/www/utils/generated/typedoc-json-output/tax-provider.json @@ -1,12 +1,12 @@ { - "id": 41934, + "id": 0, "name": "tax-provider", "variant": "project", "kind": 1, "flags": {}, "children": [ { - "id": 41935, + "id": 1, "name": "ShippingTaxCalculationLine", "variant": "declaration", "kind": 2097152, @@ -24,20 +24,20 @@ "fileName": "provider.ts", "line": 14, "character": 12, - "url": "https://github.com/medusajs/medusa/blob/f00e6bf660ab96b9d41bc3d424c8d78c54eaa8e7/packages/core/types/src/tax/provider.ts#L14" + "url": "https://github.com/medusajs/medusa/blob/95eef899f72b72aa138e9db0dffe2a3eeb40f241/packages/core/types/src/tax/provider.ts#L14" } ], "type": { "type": "reflection", "declaration": { - "id": 41936, + "id": 2, "name": "__type", "variant": "declaration", "kind": 65536, "flags": {}, "children": [ { - "id": 41937, + "id": 3, "name": "shipping_line", "variant": "declaration", "kind": 1024, @@ -55,7 +55,7 @@ "fileName": "provider.ts", "line": 18, "character": 2, - "url": "https://github.com/medusajs/medusa/blob/f00e6bf660ab96b9d41bc3d424c8d78c54eaa8e7/packages/core/types/src/tax/provider.ts#L18" + "url": "https://github.com/medusajs/medusa/blob/95eef899f72b72aa138e9db0dffe2a3eeb40f241/packages/core/types/src/tax/provider.ts#L18" } ], "type": { @@ -69,7 +69,7 @@ } }, { - "id": 41938, + "id": 4, "name": "rates", "variant": "declaration", "kind": 1024, @@ -87,7 +87,7 @@ "fileName": "provider.ts", "line": 22, "character": 2, - "url": "https://github.com/medusajs/medusa/blob/f00e6bf660ab96b9d41bc3d424c8d78c54eaa8e7/packages/core/types/src/tax/provider.ts#L22" + "url": "https://github.com/medusajs/medusa/blob/95eef899f72b72aa138e9db0dffe2a3eeb40f241/packages/core/types/src/tax/provider.ts#L22" } ], "type": { @@ -108,8 +108,8 @@ { "title": "Properties", "children": [ - 41937, - 41938 + 3, + 4 ] } ], @@ -118,14 +118,14 @@ "fileName": "provider.ts", "line": 14, "character": 41, - "url": "https://github.com/medusajs/medusa/blob/f00e6bf660ab96b9d41bc3d424c8d78c54eaa8e7/packages/core/types/src/tax/provider.ts#L14" + "url": "https://github.com/medusajs/medusa/blob/95eef899f72b72aa138e9db0dffe2a3eeb40f241/packages/core/types/src/tax/provider.ts#L14" } ] } } }, { - "id": 41939, + "id": 5, "name": "ItemTaxCalculationLine", "variant": "declaration", "kind": 2097152, @@ -143,20 +143,20 @@ "fileName": "provider.ts", "line": 29, "character": 12, - "url": "https://github.com/medusajs/medusa/blob/f00e6bf660ab96b9d41bc3d424c8d78c54eaa8e7/packages/core/types/src/tax/provider.ts#L29" + "url": "https://github.com/medusajs/medusa/blob/95eef899f72b72aa138e9db0dffe2a3eeb40f241/packages/core/types/src/tax/provider.ts#L29" } ], "type": { "type": "reflection", "declaration": { - "id": 41940, + "id": 6, "name": "__type", "variant": "declaration", "kind": 65536, "flags": {}, "children": [ { - "id": 41941, + "id": 7, "name": "line_item", "variant": "declaration", "kind": 1024, @@ -174,7 +174,7 @@ "fileName": "provider.ts", "line": 33, "character": 2, - "url": "https://github.com/medusajs/medusa/blob/f00e6bf660ab96b9d41bc3d424c8d78c54eaa8e7/packages/core/types/src/tax/provider.ts#L33" + "url": "https://github.com/medusajs/medusa/blob/95eef899f72b72aa138e9db0dffe2a3eeb40f241/packages/core/types/src/tax/provider.ts#L33" } ], "type": { @@ -188,7 +188,7 @@ } }, { - "id": 41942, + "id": 8, "name": "rates", "variant": "declaration", "kind": 1024, @@ -206,7 +206,7 @@ "fileName": "provider.ts", "line": 37, "character": 2, - "url": "https://github.com/medusajs/medusa/blob/f00e6bf660ab96b9d41bc3d424c8d78c54eaa8e7/packages/core/types/src/tax/provider.ts#L37" + "url": "https://github.com/medusajs/medusa/blob/95eef899f72b72aa138e9db0dffe2a3eeb40f241/packages/core/types/src/tax/provider.ts#L37" } ], "type": { @@ -227,8 +227,8 @@ { "title": "Properties", "children": [ - 41941, - 41942 + 7, + 8 ] } ], @@ -237,14 +237,14 @@ "fileName": "provider.ts", "line": 29, "character": 37, - "url": "https://github.com/medusajs/medusa/blob/f00e6bf660ab96b9d41bc3d424c8d78c54eaa8e7/packages/core/types/src/tax/provider.ts#L29" + "url": "https://github.com/medusajs/medusa/blob/95eef899f72b72aa138e9db0dffe2a3eeb40f241/packages/core/types/src/tax/provider.ts#L29" } ] } } }, { - "id": 41943, + "id": 9, "name": "ITaxProvider", "variant": "declaration", "kind": 256, @@ -253,55 +253,7 @@ "summary": [ { "kind": "text", - "text": "## Overview\n\nA tax provider is used to retrieve the tax lines in a provided context. The Tax Module provides a default " - }, - { - "kind": "code", - "text": "`system`" - }, - { - "kind": "text", - "text": " provider. You can create your own tax provider,\neither in a plugin, in a provider module, or directly in your Medusa application's codebase, then use it in any tax region.\n\n---\n\n## How to Create a Tax Provider\n\nA tax provider class is defined in a TypeScript or JavaScript file. The class must implement the\n" - }, - { - "kind": "code", - "text": "`ITaxProvider`" - }, - { - "kind": "text", - "text": " interface imported from " - }, - { - "kind": "code", - "text": "`@medusajs/framework/types`" - }, - { - "kind": "text", - "text": ".\n\nThe file can be defined in a plugin, a provider module, or under the " - }, - { - "kind": "code", - "text": "`src/services`" - }, - { - "kind": "text", - "text": " directory of your Medusa application. You can later pass the package's name or the\npath to the file in the " - }, - { - "kind": "code", - "text": "`providers`" - }, - { - "kind": "text", - "text": " option of the Tax Module.\n\nFor example:\n\n" - }, - { - "kind": "code", - "text": "```ts title=\"src/services/my-tax.ts\"\nimport { ITaxProvider } from \"@medusajs/framework/types\"\n\nexport default class MyTaxProvider implements ITaxProvider {\n // ...\n}\n```" - }, - { - "kind": "text", - "text": "\n\n---\n\n## Identifier Property\n\nThe " + "text": "### Identifier Property\n\nThe " }, { "kind": "code", @@ -309,7 +261,7 @@ }, { "kind": "text", - "text": " 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 " + "text": " property in a tax provider is used when the tax provider is loaded by the Tax Module and added to the database. A tax provider is represented in the database by the " }, { "kind": "code", @@ -321,11 +273,11 @@ }, { "kind": "code", - "text": "```ts title=\"src/services/my-tax.ts\"\nexport default class MyTaxProvider implements ITaxProvider {\n static identifier = \"my-tax\"\n // ...\n}\n```" + "text": "```ts title=\"src/modules/my-tax/service.ts\"\nexport default class MyTaxProvider implements ITaxProvider {\n static identifier = \"my-tax\"\n // ...\n}\n```" }, { "kind": "text", - "text": "\n\n---\n\n## Constructor\n\nYou can use the " + "text": "\n\n### constructor\n\nYou can use the " }, { "kind": "code", @@ -333,7 +285,7 @@ }, { "kind": "text", - "text": " of your tax provider to access the resources registered in the dependency container.\n\nYou 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.\n\nAdditionally, 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.\n\nFor example:\n\n" + "text": " of your tax provider to access the resources registered in the [Module Container](https://docs.medusajs.com/resources/medusa-container-resources#module-container-resources).\n\nYou 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.\n\nAdditionally, if you’re creating your tax provider as a plugin or a module provider to be installed in any Medusa application and you want to access its options, you can access them in the second parameter of the constructor.\n\nFor example:\n\n" }, { "kind": "code", @@ -347,7 +299,7 @@ }, "children": [ { - "id": 41946, + "id": 12, "name": "getTaxLines", "variant": "declaration", "kind": 2048, @@ -355,14 +307,14 @@ "sources": [ { "fileName": "provider.ts", - "line": 171, + "line": 143, "character": 2, - "url": "https://github.com/medusajs/medusa/blob/f00e6bf660ab96b9d41bc3d424c8d78c54eaa8e7/packages/core/types/src/tax/provider.ts#L171" + "url": "https://github.com/medusajs/medusa/blob/95eef899f72b72aa138e9db0dffe2a3eeb40f241/packages/core/types/src/tax/provider.ts#L143" } ], "signatures": [ { - "id": 41947, + "id": 13, "name": "getTaxLines", "variant": "signature", "kind": 4096, @@ -371,7 +323,7 @@ "summary": [ { "kind": "text", - "text": "This method is used to retrieve the tax lines of items and shipping methods. It's used\nwhen the " + "text": "This method is used to retrieve the tax lines of items and shipping methods. It's used during checkout \nwhen the " }, { "kind": "code", @@ -379,7 +331,7 @@ }, { "kind": "text", - "text": " method of the Tax Module's main service is called.\n\nThis method is useful during checkout or when calculating the totals of orders or exchanges." + "text": " method of the Tax Module's main service is called for a tax\nregion that uses this tax provider." } ], "blockTags": [ @@ -434,14 +386,14 @@ "sources": [ { "fileName": "provider.ts", - "line": 171, + "line": 143, "character": 2, - "url": "https://github.com/medusajs/medusa/blob/f00e6bf660ab96b9d41bc3d424c8d78c54eaa8e7/packages/core/types/src/tax/provider.ts#L171" + "url": "https://github.com/medusajs/medusa/blob/95eef899f72b72aa138e9db0dffe2a3eeb40f241/packages/core/types/src/tax/provider.ts#L143" } ], "parameters": [ { - "id": 41948, + "id": 14, "name": "itemLines", "variant": "param", "kind": 32768, @@ -458,14 +410,14 @@ "type": "array", "elementType": { "type": "reference", - "target": 41939, + "target": 5, "name": "ItemTaxCalculationLine", "package": "@medusajs/types" } } }, { - "id": 41949, + "id": 15, "name": "shippingLines", "variant": "param", "kind": 32768, @@ -482,14 +434,14 @@ "type": "array", "elementType": { "type": "reference", - "target": 41935, + "target": 1, "name": "ShippingTaxCalculationLine", "package": "@medusajs/types" } } }, { - "id": 41950, + "id": 16, "name": "context", "variant": "param", "kind": 32768, @@ -558,16 +510,16 @@ { "title": "Methods", "children": [ - 41946 + 12 ] } ], "sources": [ { "fileName": "provider.ts", - "line": 108, + "line": 81, "character": 17, - "url": "https://github.com/medusajs/medusa/blob/f00e6bf660ab96b9d41bc3d424c8d78c54eaa8e7/packages/core/types/src/tax/provider.ts#L108" + "url": "https://github.com/medusajs/medusa/blob/95eef899f72b72aa138e9db0dffe2a3eeb40f241/packages/core/types/src/tax/provider.ts#L81" } ] } @@ -576,76 +528,76 @@ { "title": "Interfaces", "children": [ - 41943 + 9 ] }, { "title": "Type Aliases", "children": [ - 41935, - 41939 + 1, + 5 ] } ], "packageName": "@medusajs/types", "symbolIdMap": { - "41934": { + "0": { "sourceFileName": "../../../../packages/core/types/src/tax/provider.ts", "qualifiedName": "" }, - "41935": { + "1": { "sourceFileName": "../../../../packages/core/types/src/tax/provider.ts", "qualifiedName": "ShippingTaxCalculationLine" }, - "41936": { + "2": { "sourceFileName": "../../../../packages/core/types/src/tax/provider.ts", "qualifiedName": "__type" }, - "41937": { + "3": { "sourceFileName": "../../../../packages/core/types/src/tax/provider.ts", "qualifiedName": "__type.shipping_line" }, - "41938": { + "4": { "sourceFileName": "../../../../packages/core/types/src/tax/provider.ts", "qualifiedName": "__type.rates" }, - "41939": { + "5": { "sourceFileName": "../../../../packages/core/types/src/tax/provider.ts", "qualifiedName": "ItemTaxCalculationLine" }, - "41940": { + "6": { "sourceFileName": "../../../../packages/core/types/src/tax/provider.ts", "qualifiedName": "__type" }, - "41941": { + "7": { "sourceFileName": "../../../../packages/core/types/src/tax/provider.ts", "qualifiedName": "__type.line_item" }, - "41942": { + "8": { "sourceFileName": "../../../../packages/core/types/src/tax/provider.ts", "qualifiedName": "__type.rates" }, - "41943": { + "9": { "sourceFileName": "../../../../packages/core/types/src/tax/provider.ts", "qualifiedName": "ITaxProvider" }, - "41946": { + "12": { "sourceFileName": "../../../../packages/core/types/src/tax/provider.ts", "qualifiedName": "ITaxProvider.getTaxLines" }, - "41947": { + "13": { "sourceFileName": "../../../../packages/core/types/src/tax/provider.ts", "qualifiedName": "ITaxProvider.getTaxLines" }, - "41948": { + "14": { "sourceFileName": "../../../../packages/core/types/src/tax/provider.ts", "qualifiedName": "itemLines" }, - "41949": { + "15": { "sourceFileName": "../../../../packages/core/types/src/tax/provider.ts", "qualifiedName": "shippingLines" }, - "41950": { + "16": { "sourceFileName": "../../../../packages/core/types/src/tax/provider.ts", "qualifiedName": "context" } @@ -655,7 +607,7 @@ "1": "../../../../packages/core/types/src/tax/provider.ts" }, "reflections": { - "1": 41934 + "1": 0 } } } diff --git a/www/utils/packages/typedoc-generate-references/src/constants/merger-custom-options/auth-provider.ts b/www/utils/packages/typedoc-generate-references/src/constants/merger-custom-options/auth-provider.ts index ffde33c753..9afbf6b3ac 100644 --- a/www/utils/packages/typedoc-generate-references/src/constants/merger-custom-options/auth-provider.ts +++ b/www/utils/packages/typedoc-generate-references/src/constants/merger-custom-options/auth-provider.ts @@ -27,6 +27,7 @@ const authProviderOptions: FormattingOptionsType = { Start by creating a new directory for your module provider. If you're creating the module provider in a Medusa application, create it under the \`src/modules\` directory. For example, \`src/modules/my-auth\`. + If you're creating the module provider in a plugin, create it under the \`src/providers\` directory. For example, \`src/providers/my-auth\`. diff --git a/www/utils/packages/typedoc-generate-references/src/constants/merger-custom-options/file.ts b/www/utils/packages/typedoc-generate-references/src/constants/merger-custom-options/file.ts index 007ec14355..702dc51d77 100644 --- a/www/utils/packages/typedoc-generate-references/src/constants/merger-custom-options/file.ts +++ b/www/utils/packages/typedoc-generate-references/src/constants/merger-custom-options/file.ts @@ -27,6 +27,7 @@ const fileOptions: FormattingOptionsType = { Start by creating a new directory for your module provider. If you're creating the module provider in a Medusa application, create it under the \`src/modules\` directory. For example, \`src/modules/my-file\`. + If you're creating the module provider in a plugin, create it under the \`src/providers\` directory. For example, \`src/providers/my-file\`. diff --git a/www/utils/packages/typedoc-generate-references/src/constants/merger-custom-options/fulfillment-provider.ts b/www/utils/packages/typedoc-generate-references/src/constants/merger-custom-options/fulfillment-provider.ts index 08e6c2d85a..6b238fcec4 100644 --- a/www/utils/packages/typedoc-generate-references/src/constants/merger-custom-options/fulfillment-provider.ts +++ b/www/utils/packages/typedoc-generate-references/src/constants/merger-custom-options/fulfillment-provider.ts @@ -33,6 +33,7 @@ For example, when the merchant creates a fulfillment for an order, the Fulfillme Start by creating a new directory for your module provider. If you're creating the module provider in a Medusa application, create it under the \`src/modules\` directory. For example, \`src/modules/my-fulfillment\`. + If you're creating the module provider in a plugin, create it under the \`src/providers\` directory. For example, \`src/providers/my-fulfillment\`. diff --git a/www/utils/packages/typedoc-generate-references/src/constants/merger-custom-options/notification.ts b/www/utils/packages/typedoc-generate-references/src/constants/merger-custom-options/notification.ts index dac471be56..d118f53e9a 100644 --- a/www/utils/packages/typedoc-generate-references/src/constants/merger-custom-options/notification.ts +++ b/www/utils/packages/typedoc-generate-references/src/constants/merger-custom-options/notification.ts @@ -27,6 +27,7 @@ const notificationOptions: FormattingOptionsType = { Start by creating a new directory for your module provider. If you're creating the module provider in a Medusa application, create it under the \`src/modules\` directory. For example, \`src/modules/my-notification\`. + If you're creating the module provider in a plugin, create it under the \`src/providers\` directory. For example, \`src/providers/my-notification\`. diff --git a/www/utils/packages/typedoc-generate-references/src/constants/merger-custom-options/payment-provider.ts b/www/utils/packages/typedoc-generate-references/src/constants/merger-custom-options/payment-provider.ts index ebff040872..b8513bd08e 100644 --- a/www/utils/packages/typedoc-generate-references/src/constants/merger-custom-options/payment-provider.ts +++ b/www/utils/packages/typedoc-generate-references/src/constants/merger-custom-options/payment-provider.ts @@ -33,6 +33,7 @@ For example, when the merchant captures an order's payment, the Payment Module u Start by creating a new directory for your module provider. If you're creating the module provider in a Medusa application, create it under the \`src/modules\` directory. For example, \`src/modules/my-payment\`. + If you're creating the module provider in a plugin, create it under the \`src/providers\` directory. For example, \`src/providers/my-payment\`. diff --git a/www/utils/packages/typedoc-generate-references/src/constants/merger-custom-options/tax-provider.ts b/www/utils/packages/typedoc-generate-references/src/constants/merger-custom-options/tax-provider.ts index b760e3008f..61b52d5b40 100644 --- a/www/utils/packages/typedoc-generate-references/src/constants/merger-custom-options/tax-provider.ts +++ b/www/utils/packages/typedoc-generate-references/src/constants/merger-custom-options/tax-provider.ts @@ -12,6 +12,89 @@ const taxProviderOptions: FormattingOptionsType = { reflectionTitle: { fullReplacement: "How to Create a Tax Provider", }, + shouldIncrementAfterStartSections: true, + expandMembers: true, + expandProperties: true, + startSections: [ + `## 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 module provider, or directly in your Medusa application's codebase, then use it in any tax region.`, + `## Understanding Tax Provider Implementation + +The Tax Module Provider handles calculating taxes with a third-party provirder. However, it's not responsible for managing tax concepts within Medusa, such as creating a tax region. The Tax Module uses your tax provider within core operations. + +For example, during checkout, the tax provider of the tax region that the customer is in is used to calculate the tax for the cart and order. So, you only have to implement the third-party tax calculation logic in your tax provider.`, + `## 1. Create Module Provider Directory + +Start by creating a new directory for your module provider. + +If you're creating the module provider in a Medusa application, create it under the \`src/modules\` directory. For example, \`src/modules/my-tax\`. + +If you're creating the module provider in a plugin, create it under the \`src/providers\` directory. For example, \`src/providers/my-tax\`. + + + +The rest of this guide always uses the \`src/modules/my-tax\` directory as an example. + +`, + `## 2. Create the Tax Provider Service + +Create the file \`src/modules/my-tax/service.ts\` that holds the module's main service. It must extend the \`ITaxProvider\` class imported from \`@medusajs/framework/types\`: + +\`\`\`ts title="src/modules/my-tax/service.ts" +import { ITaxProvider } from "@medusajs/framework/types" + +export default class MyTaxProvider implements ITaxProvider { + // TODO implement methods +} +\`\`\``, + ], + endSections: [ + `## 3. Create Module Definition File + +Create the file \`src/modules/my-tax/index.ts\` with the following content: + +\`\`\`ts title="src/modules/my-tax/index.ts" +import MyTaxProvider from "./service" +import { + ModuleProvider, + Modules +} from "@medusajs/framework/utils" + +export default ModuleProvider(Modules.TAX, { + services: [MyTaxProvider], +}) +\`\`\` + +This exports the module's definition, indicating that the \`MyTaxProvider\` is the module's service.`, + `## 4. Use Module + +To use your Tax Module Provider, add it to the \`providers\` array of the Tax Module in \`medusa-config.ts\`: + +\`\`\`ts title="medusa-config.ts" +module.exports = defineConfig({ + // ... + modules: [ + { + resolve: "@medusajs/medusa/tax", + options: { + providers: [ + { + // if module provider is in a plugin, use \`plugin-name/providers/my-tax\` + resolve: "./src/modules/my-tax", + id: "my-tax", + options: { + // provider options... + }, + }, + ], + }, + }, + ] +}) +\`\`\` +`, + ], }, }