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

docs: updates to tax provider and other provider guides (#11626)

Browse Source
This commit is contained in:
Shahed Nasser
2025-02-26 16:13:05 +02:00
committed by GitHub
parent 65eb3aa6c8
commit 0eadcdd555
13 changed files with 246 additions and 138 deletions
Download Patch File Download Diff File Expand all files Collapse all files

1
www/apps/resources/references/auth_provider/classes/auth_provider.AbstractAuthModuleProvider/page.mdx
View File

@@ -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`.
<Note>

1
www/apps/resources/references/file/classes/file.AbstractFileProviderService/page.mdx
View File

@@ -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`.
<Note>

1
www/apps/resources/references/fulfillment_provider/classes/fulfillment_provider.AbstractFulfillmentProviderService/page.mdx
View File

@@ -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`.
<Note>

1
www/apps/resources/references/notification/classes/notification.AbstractNotificationProviderService/page.mdx
View File

@@ -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`.
<Note>

1
www/apps/resources/references/payment_provider/classes/payment_provider.AbstractPaymentProvider/page.mdx
View File

@@ -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`.
<Note>

119
www/apps/resources/references/tax_provider/interfaces/tax_provider.ITaxProvider/page.mdx
View File

File diff suppressed because one or more lines are too long

172
www/utils/generated/typedoc-json-output/tax-provider.json
View File

@@ -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
}
}
}

1
www/utils/packages/typedoc-generate-references/src/constants/merger-custom-options/auth-provider.ts
View File

@@ -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\`.
<Note>

1
www/utils/packages/typedoc-generate-references/src/constants/merger-custom-options/file.ts
View File

@@ -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\`.
<Note>

1
www/utils/packages/typedoc-generate-references/src/constants/merger-custom-options/fulfillment-provider.ts
View File

@@ -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\`.
<Note>

1
www/utils/packages/typedoc-generate-references/src/constants/merger-custom-options/notification.ts
View File

@@ -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\`.
<Note>

1
www/utils/packages/typedoc-generate-references/src/constants/merger-custom-options/payment-provider.ts
View File

@@ -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\`.
<Note>

83
www/utils/packages/typedoc-generate-references/src/constants/merger-custom-options/tax-provider.ts
View File

@@ -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\`.
<Note>
The rest of this guide always uses the \`src/modules/my-tax\` directory as an example.
</Note>`,
`## 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...
},
},
],
},
},
]
})
\`\`\`
`,
],
},
}