chore: reorganize docs apps (#7228)

* reorganize docs apps

* add README

* fix directory

* add condition for old docs

www/apps/resources/app/commerce-modules/tax/examples/page.mdx

@@ -0,0 +1,359 @@
+import { CodeTabs, CodeTab } from "docs-ui"
+
+export const metadata = {
+  title: `Examples of the Tax Module`,
+}
+
+# {metadata.title}
+
+In this guide, you’ll find common examples of how you can use the Tax Module in your application.
+
+## Create a Tax Region
+
+<CodeTabs groupId="app-type">
+  <CodeTab label="Medusa API Router" value="medusa">
+
+  ```ts
+  import { MedusaRequest, MedusaResponse } from "@medusajs/medusa"
+  import { ITaxModuleService } from "@medusajs/types"
+  import { ModuleRegistrationName } from "@medusajs/modules-sdk"
+
+  export async function GET(
+    req: MedusaRequest,
+    res: MedusaResponse
+  ): Promise<void> {
+    const taxModuleService: ITaxModuleService = req.scope.resolve(
+      ModuleRegistrationName.TAX
+    )
+
+    const taxRegion = await taxModuleService.createTaxRegions({
+      country_code: "US",
+      default_tax_rate: {
+        rate: 10,
+        name: "Default rate",
+      },
+    })
+
+    res.json({
+      tax_region: taxRegion,
+    })
+  }
+  ```
+
+  </CodeTab>
+  <CodeTab label="Next.js App Router" value="nextjs">
+
+  ```ts
+  import { NextResponse } from "next/server"
+
+  import {
+    initialize as initializeTaxModule,
+  } from "@medusajs/tax"
+
+  export async function POST(request: Request) {
+    const taxModuleService = await initializeTaxModule()
+
+    const taxRegion = await taxModuleService.createTaxRegions({
+      country_code: "US",
+      default_tax_rate: {
+        rate: 10,
+        name: "Default rate",
+      },
+    })
+
+    return NextResponse.json({
+      tax_region: taxRegion,
+    })
+  }
+  ```
+
+  </CodeTab>
+</CodeTabs>
+
+---
+
+## List Tax Regions
+
+<CodeTabs groupId="app-type">
+  <CodeTab label="Medusa API Router" value="medusa">
+
+  ```ts
+  import { MedusaRequest, MedusaResponse } from "@medusajs/medusa"
+  import { ITaxModuleService } from "@medusajs/types"
+  import { ModuleRegistrationName } from "@medusajs/modules-sdk"
+
+  export async function GET(
+    req: MedusaRequest,
+    res: MedusaResponse
+  ): Promise<void> {
+    const taxModuleService: ITaxModuleService = req.scope.resolve(
+      ModuleRegistrationName.TAX
+    )
+
+    res.json({
+      tax_regions: await taxModuleService.list(),
+    })
+  }
+  ```
+
+  </CodeTab>
+  <CodeTab label="Next.js App Router" value="nextjs">
+
+  ```ts
+  import { NextResponse } from "next/server"
+
+  import {
+    initialize as initializeTaxModule,
+  } from "@medusajs/tax"
+
+  export async function GET(request: Request) {
+    const taxModuleService = await initializeTaxModule()
+
+    return NextResponse.json({
+      tax_regions: await taxModuleService.list(),
+    })
+  }
+  ```
+
+  </CodeTab>
+</CodeTabs>
+
+---
+
+## Create Tax Rate with Rules
+
+<CodeTabs groupId="app-type">
+  <CodeTab label="Medusa API Router" value="medusa">
+
+  ```ts
+  import { MedusaRequest, MedusaResponse } from "@medusajs/medusa"
+  import { ITaxModuleService } from "@medusajs/types"
+  import { ModuleRegistrationName } from "@medusajs/modules-sdk"
+
+  export async function POST(
+    req: MedusaRequest,
+    res: MedusaResponse
+  ): Promise<void> {
+    const taxModuleService: ITaxModuleService = req.scope.resolve(
+      ModuleRegistrationName.TAX
+    )
+
+    const taxRate = await taxModuleService.create({
+      tax_region_id: "txreg_123",
+      name: "Custom rate",
+      rate: 15,
+      rules: [
+        {
+          reference: "product_type",
+          reference_id: "ptyp_1",
+        },
+        {
+          reference: "product",
+          reference_id: "prod_123",
+        },
+      ],
+    })
+
+    res.json({
+      tax_rate: taxRate,
+    })
+  }
+  ```
+
+  </CodeTab>
+  <CodeTab label="Next.js App Router" value="nextjs">
+
+  ```ts
+  import { NextResponse } from "next/server"
+
+  import {
+    initialize as initializeTaxModule,
+  } from "@medusajs/tax"
+
+  export async function POST(
+    request: Request
+  ) {
+    const taxModuleService = await initializeTaxModule()
+
+    const taxRate = await taxModuleService.create({
+      tax_region_id: "txreg_123",
+      name: "Custom rate",
+      rate: 15,
+      rules: [
+        {
+          reference: "product_type",
+          reference_id: "ptyp_1",
+        },
+        {
+          reference: "product",
+          reference_id: "prod_123",
+        },
+      ],
+    })
+
+    return NextResponse.json({
+      tax_rate: taxRate,
+    })
+  }
+  ```
+
+  </CodeTab>
+</CodeTabs>
+
+---
+
+## List Tax Rates
+
+<CodeTabs groupId="app-type">
+  <CodeTab label="Medusa API Router" value="medusa">
+
+  ```ts
+  import { MedusaRequest, MedusaResponse } from "@medusajs/medusa"
+  import { ITaxModuleService } from "@medusajs/types"
+  import { ModuleRegistrationName } from "@medusajs/modules-sdk"
+
+  export async function GET(
+    req: MedusaRequest,
+    res: MedusaResponse
+  ): Promise<void> {
+    const taxModuleService: ITaxModuleService = req.scope.resolve(
+      ModuleRegistrationName.TAX
+    )
+
+    res.json({
+      tax_rates: await taxModuleService.list(),
+    })
+  }
+  ```
+
+  </CodeTab>
+  <CodeTab label="Next.js App Router" value="nextjs">
+
+  ```ts
+  import { NextResponse } from "next/server"
+
+  import {
+    initialize as initializeTaxModule,
+  } from "@medusajs/tax"
+
+  export async function GET(
+    request: Request
+  ) {
+    const taxModuleService = await initializeTaxModule()
+
+    return NextResponse.json({
+      tax_rates: await taxModuleService.list(),
+    })
+  }
+  ```
+
+  </CodeTab>
+</CodeTabs>
+
+---
+
+## Get Tax Lines
+
+<CodeTabs groupId="app-type">
+  <CodeTab label="Medusa API Router" value="medusa">
+
+  ```ts
+  import { MedusaRequest, MedusaResponse } from "@medusajs/medusa"
+  import { ITaxModuleService } from "@medusajs/types"
+  import { ModuleRegistrationName } from "@medusajs/modules-sdk"
+
+  export async function POST(
+    req: MedusaRequest,
+    res: MedusaResponse
+  ): Promise<void> {
+    const taxModuleService: ITaxModuleService = req.scope.resolve(
+      ModuleRegistrationName.TAX
+    )
+
+    const taxLines = await taxModuleService.getTaxLines(
+      [
+        {
+          id: "cali_123",
+          product_id: "prod_123",
+          unit_price: 1000,
+        },
+        {
+          id: "casm_123",
+          shipping_option_id: "so_123",
+          unit_price: 2000,
+        },
+      ],
+      {
+        address: {
+          country_code: "us",
+          postal_code: "123456",
+        },
+        customer: {
+          id: "cus_123",
+          email: "user@example.com",
+          customer_groups: ["VIP"],
+        },
+      }
+    )
+
+    res.json({
+      tax_lines: taxLines,
+    })
+  }
+  ```
+
+  </CodeTab>
+  <CodeTab label="Next.js App Router" value="nextjs">
+
+  ```ts
+  import { NextResponse } from "next/server"
+
+  import {
+    initialize as initializeTaxModule,
+  } from "@medusajs/tax"
+
+  export async function POST(
+    request: Request
+  ) {
+    const taxModuleService = await initializeTaxModule()
+
+    const taxLines = await taxModuleService.getTaxLines(
+      [
+        {
+          id: "cali_123",
+          product_id: "prod_123",
+          unit_price: 1000,
+        },
+        {
+          id: "casm_123",
+          shipping_option_id: "so_123",
+          unit_price: 2000,
+        },
+      ],
+      {
+        address: {
+          country_code: "us",
+          postal_code: "123456",
+        },
+        customer: {
+          id: "cus_123",
+          email: "user@example.com",
+          customer_groups: ["VIP"],
+        },
+      }
+    )
+
+    return NextResponse.json({
+      tax_lines: taxLines,
+    })
+  }
+  ```
+
+  </CodeTab>
+</CodeTabs>
+
+---
+
+## More Examples
+
+The [module interface reference](/references/tax) provides a reference to all the methods available for use with examples for each.

www/apps/resources/app/commerce-modules/tax/module-options/page.mdx

@@ -0,0 +1,43 @@
+---
+sidebar_label: "Module Options"
+---
+
+import { Table } from "docs-ui"
+
+export const metadata = {
+  title: `Tax Module Options`,
+}
+
+# {metadata.title}
+
+In this document, you'll learn about the options of the Tax Module.
+
+## providers
+
+The `providers` option is an array of either tax provider modules, tax plugins, or path to a file that defines a tax provider.
+
+When the Medusa application starts, these providers are registered and can be used to retrieve tax lines.
+
+```js title="medusa-config.js"
+const modules = {
+  // ...
+  tax: {
+    resolve: "@medusajs/tax",
+    options: {
+      providers: [
+        {
+          resolve: "my-provider",
+          options: {
+            // ...
+          },
+        },
+      ],
+    },
+  },
+}
+```
+
+The objects in the array accept the following properties:
+
+- `resolve`: A string indicating the package name of the tax provider module or the tax plugin, or the path to the file defining the tax provider.
+- `options`: An object of options to pass to the tax provider.

www/apps/resources/app/commerce-modules/tax/page.mdx

@@ -0,0 +1,164 @@
+import { CodeTabs, CodeTab } from "docs-ui"
+
+export const metadata = {
+  title: `Tax Module`,
+}
+
+# {metadata.title}
+
+The Tax Module is the `@medusajs/tax` NPM package that provides tax-related features in your Medusa and Node.js applications.
+
+---
+
+## Features
+
+### Tax Settings Per Region
+
+Set different tax settings for each region. This is especially useful with the [Region Module](../region/page.mdx).
+
+```ts
+const taxRegion = await taxModuleService.createTaxRegions({
+  country_code: "us",
+})
+```
+
+### Tax Rates and Rules
+
+Manage each region's default tax rates and override them with conditioned tax rates.
+
+```ts
+const taxRates = await taxModuleService.create([
+  {
+    tax_region_id: "txreg_123",
+    name: "Default tax rate",
+    is_default: true,
+    rate: 10,
+  },
+  {
+    tax_region_id: "txreg_123",
+    name: "Shirt product type",
+    is_default: false,
+    rate: 15,
+    rules: [
+      {
+        reference: "product_type",
+        reference_id: "ptyp_1",
+      },
+    ],
+  },
+])
+```
+
+### Retrieve Cart's Tax Lines
+
+Calculate and retrieve the tax lines of a cart's line items and shipping methods with tax providers. Use different tax providers for each region to handle tax-line retrieval differently.
+
+```ts
+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",
+    },
+  }
+)
+```
+
+---
+
+## Configure Tax Module
+
+After installing the `@medusajs/tax` package in your Medusa application, add it to the `modules` object in `medusa-config.js`:
+
+```js title="medusa-config.js"
+const modules = {
+  // ...
+  tax: {
+    resolve: "@medusajs/tax",
+  },
+}
+```
+
+### Module Options
+
+Refer to [this documentation](./module-options/page.mdx) for details on the module's options.
+
+---
+
+## How to Use Tax Module's Service
+
+You can use the Tax Module's main service by resolving from the Medusa container the resource `ModuleRegistrationName.TAX` imported from `@medusajs/modules-sdk`.
+
+For example:
+
+<CodeTabs groupId="resource-type">
+  <CodeTab label="API Route" value="api-route">
+
+  ```ts title="src/api/store/custom/route.ts"
+  import { MedusaRequest, MedusaResponse } from "@medusajs/medusa"
+  import { ITaxModuleService } from "@medusajs/types"
+  import { ModuleRegistrationName } from "@medusajs/modules-sdk"
+
+  export async function GET(
+    req: MedusaRequest,
+    res: MedusaResponse
+  ): Promise<void> {
+    const taxModuleService: ITaxModuleService = req.scope.resolve(
+      ModuleRegistrationName.TAX
+    )
+
+    res.json({
+      tax_regions: await taxModuleService.listTaxRegions(),
+    })
+  }
+  ```
+
+  </CodeTab>
+  <CodeTab label="Subscriber" value="subscribers">
+
+  ```ts title="src/subscribers/custom-handler.ts"
+  import { SubscriberArgs } from "@medusajs/medusa"
+  import { ITaxModuleService } from "@medusajs/types"
+  import { ModuleRegistrationName } from "@medusajs/modules-sdk"
+
+  export default async function subscriberHandler({
+    container,
+  }: SubscriberArgs) {
+    const taxModuleService: ITaxModuleService =
+      container.resolve(ModuleRegistrationName.TAX)
+
+    const taxRegions = await taxModuleService.listTaxRegions()
+  }
+  ```
+
+  </CodeTab>
+  <CodeTab label="Workflow Step" value="workflow-step">
+
+  ```ts title="src/workflows/hello-world/step1.ts"
+  import { createStep } from "@medusajs/workflows-sdk"
+  import { ITaxModuleService } from "@medusajs/types"
+  import { ModuleRegistrationName } from "@medusajs/modules-sdk"
+
+  const step1 = createStep("step-1", async (_, context) => {
+    const taxModuleService: ITaxModuleService =
+      context.container.resolve(
+        ModuleRegistrationName.TAX
+      )
+    const taxRegions = await taxModuleService.listTaxRegions()
+  })
+  ```
+
+  </CodeTab>
+</CodeTabs>

www/apps/resources/app/commerce-modules/tax/tax-calculation-with-provider/page.mdx

@@ -0,0 +1,66 @@
+export const metadata = {
+  title: `Tax Calculation with the Tax Provider`,
+}
+
+# {metadata.title}
+
+In this document, you’ll learn how tax lines are calculated and what a tax provider is.
+
+## Tax Lines Calculation
+
+Tax lines are calculated and retrieved using the `getTaxLines` method of the Tax Module’s main service (`ITaxModuleService`). It accepts an array of line items and shipping methods, and the context of the calculation.
+
+It returns the tax lines that are used to adjust the cart’s tax and grand totals.
+
+```ts
+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",
+    },
+  }
+)
+```
+
+The context object is used to determine which tax regions and rates to use in the calculation. The object includes fields related to the address and customer.
+
+<Note>
+
+Learn more about the `getTaxLines` method’s parameters and return type in [this reference](/references/tax/getTaxLines).
+
+</Note>
+
+The example above returns the tax lines based on the tax region for the United States.
+
+---
+
+## Tax Provider Usage in the Calculation
+
+The tax lines retrieved by the `getTaxLines` method are actually retrieved from the tax region’s provider.
+
+A tax provider is a TypeScript or JavaScript class that implements the logic to shape tax lines. Each tax region has a tax provider.
+
+The Tax Module provides a `system` tax provider that only transforms calculated item and shipping tax rates into the required return type.
+
+---
+
+## Create Tax Provider
+
+You can create a tax provider by implementing the `ITaxProvider` imported from `@meduasjs/types`.
+
+Then, you can add the tax provider to the [providers](../module-options/page.mdx#providers) option and use it to retrieve tax lines.
+
+Refer to [this reference](/modules/tax/provider) to learn more about creating a tax provider.

www/apps/resources/app/commerce-modules/tax/tax-rates-and-rules/page.mdx

@@ -0,0 +1,36 @@
+export const metadata = {
+  title: `Tax Rates and Rules`,
+}
+
+# {metadata.title}
+
+In this document, you’ll learn about tax rates and rules.
+
+## What are Tax Rates?
+
+A tax rate is a percentage amount used to calculate the tax amount for each taxable item’s price, such as line items or shipping methods, in a cart. The sum of all calculated tax amounts are then added to the cart’s total as a tax total.
+
+Each tax region has a default tax rate. This tax rate is applied to all taxable items of a cart in that region.
+
+### Combinable Tax Rates
+
+Tax regions can have parent tax regions. To inherit the tax rates of the parent tax region, set the `is_combinable` of the child’s tax rates to `true`.
+
+Then, when tax rates are retrieved for a taxable item in the child region, both the child and the parent tax regions’ applicable rates are returned. Otherwise, only the child tax region’s applicable rates are returned.
+
+---
+
+## What are Tax Rules?
+
+You can also create tax rates that override the default for specific conditions or rules. For example, the default tax rate is 10%, but for products of type “Shirt” is %15.
+
+A tax region can have multiple tax rates, and each tax rate can have multiple tax rules. The `TaxRateRule` data model represents a tax rate’s rule.
+
+![A diagram showcasing the relation between TaxRegion, TaxRate, and TaxRateRule](https://res.cloudinary.com/dza7lstvk/image/upload/v1711462167/Medusa%20Resources/tax-rate-rule_enzbp2.jpg)
+
+These two fields of the data model identify the rule’s target:
+
+- `reference`: the name of the table in the database that this rule points to. For example, `product_type`.
+- `reference_id`: the ID of the data model’s record that this points to. For example, a product type’s ID.
+
+So, to override the default tax rate for product types “Shirt”, you create a tax rate and associate with it a tax rule whose `reference` is `product_type` and `reference_id` the ID of the “Shirt” product type.

www/apps/resources/app/commerce-modules/tax/tax-region/page.mdx

@@ -0,0 +1,25 @@
+export const metadata = {
+  title: `Tax Region`,
+}
+
+# {metadata.title}
+
+In this document, you’ll learn about tax regions and how to use them with the Region Module.
+
+## What is a Tax Region?
+
+A tax region, represented by the `TaxRegion` data model, stores settings related to a region that your store serves.
+
+Tax regions can inherit settings and rules from a parent tax region.
+
+Each tax region has tax rules and a tax provider.
+
+---
+
+## Settings Per Region with the Region Module
+
+By combining the Tax and [Region](../../region/page.mdx) Modules, as done in the Medusa application, each region has its own tax providers and rates.
+
+This adds more flexibility to your commerce store.
+
+![Diagram showcasing the relation between the Tax and Region Modules](https://res.cloudinary.com/dza7lstvk/image/upload/v1711454031/Medusa%20Resources/tax-region_adr4kz.jpg)