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

docs: revise commerce modules overview pages (#10738)

Browse Source 
* revise API Key Module overview

* revise auth module

* support ref sidebar items

* remove examples

* revise cart module

* revise currency

* revise customer module

* revise fulfillment module

* revise inventory module

* revise order module

* revise payment

* revise pricing module

* revise product module

* revise promotion module

* revise region module

* revise sales channel module

* revise stock location module

* revise store module

* revise tax module

* revise user module

* lint content + fix snippets
This commit is contained in:
Shahed Nasser
2024-12-26 10:32:16 +02:00
committed by GitHub
parent c8f9938865
commit ebca8fed28
112 changed files with 9465 additions and 7731 deletions
Download Patch File Download Diff File Expand all files Collapse all files
www/apps/resources/app/commerce-modules/currency/examples/page.mdx
-111
View File
@@ -1,111 +0,0 @@
import { CodeTabs, CodeTab } from "docs-ui"
export const metadata = {
title: `Examples of the Currency Module`,
}
# {metadata.title}
In this guide, you’ll find common examples of how you can use the Currency Module in your application.
<Note>
You should only use the Currency Module's main service when implementing complex customizations. For common cases, check out [available workflows instead](../../../medusa-workflows-reference/page.mdx).
</Note>
## List Currencies
<CodeTabs groupId="app-type">
<CodeTab label="Medusa API Router" value="medusa">
```ts
import { MedusaRequest, MedusaResponse } from "@medusajs/framework/http"
import { Modules } from "@medusajs/framework/utils"
export async function GET(
req: MedusaRequest,
res: MedusaResponse
): Promise<void> {
const currencyModuleService = req.scope.resolve(
Modules.CURRENCY
)
res.json({
currencies: await currencyModuleService.listCurrencies(),
})
}
```
</CodeTab>
<CodeTab label="Next.js App Router" value="nextjs">
```ts
import { NextResponse } from "next/server"
import { initialize as initializeCurrencyModule } from "@medusajs/medusa/currency"
export async function GET(request: Request) {
const currencyModuleService = await initializeCurrencyModule()
return NextResponse.json({
currencies: await currencyModuleService.listCurrencies(),
})
}
```
</CodeTab>
</CodeTabs>
---
## Retrieve a Currency by its Code
<CodeTabs groupId="app-type">
<CodeTab label="Medusa API Router" value="medusa">
```ts
import { MedusaRequest, MedusaResponse } from "@medusajs/framework/http"
import { Modules } from "@medusajs/framework/utils"
export async function GET(
req: MedusaRequest,
res: MedusaResponse
): Promise<void> {
const currencyModuleService = req.scope.resolve(
Modules.CURRENCY
)
const currency = await currencyModuleService.retrieveCurrency("usd")
res.json({
currency,
})
}
```
</CodeTab>
<CodeTab label="Next.js App Router" value="nextjs">
```ts
import { NextResponse } from "next/server"
import { initialize as initializeCurrencyModule } from "@medusajs/medusa/currency"
export async function GET(request: Request) {
const currencyModuleService = await initializeCurrencyModule()
const currency = await currencyModuleService.retrieveCurrency("usd")
return NextResponse.json({ currency })
}
```
</CodeTab>
</CodeTabs>
---
## More Examples
The [Currency Module's main service reference](/references/currency) provides a reference to all the methods available for use with examples for each.
www/apps/resources/app/commerce-modules/currency/links-to-other-modules/page.mdx
+4 -4
View File
@@ -39,8 +39,8 @@ To retrieve the details of a store's currencies with [Query](!docs!/learn/fundam
const { data: stores } = await query.graph({
entity: "store",
fields: [
"supported_currencies.currency.*"
]
"supported_currencies.currency.*",
],
})
// stores.supported_currencies
@@ -57,8 +57,8 @@ import { useQueryGraphStep } from "@medusajs/medusa/core-flows"
const { data: stores } = useQueryGraphStep({
entity: "store",
fields: [
"supported_currencies.currency.*"
]
"supported_currencies.currency.*",
],
})
// stores.supported_currencies
www/apps/resources/app/commerce-modules/currency/page.mdx
+126 -56
View File
@@ -6,91 +6,161 @@ export const metadata = {
# {metadata.title}
The Currency Module provides currency-related features in your Medusa and Node.js applications.
In this section of the documentation, you will find resources to learn more about the Currency Module and how to use it in your application.
## How to Use Currency Module's Service
Medusa has currency related features available out-of-the-box through the Currency Module. A [module](!docs!/learn/fundamentals/modules) is a standalone package that provides features for a single domain. Each of Medusa's commerce features are placed in commerce modules, such as this Currency Module.
You can use the Currency Module's main service by resolving from the Medusa container the resource `Modules.CURRENCY`.
<Note>
Learn more about why modules are isolated in [this documentation](!docs!/learn/fundamentals/modules/isolation).
</Note>
## Currency Features
- [Currency Management and Retrieval](/references/currency/listAndCountCurrencies): This module adds all common currencies to your application and allows you to retrieve them.
- [Support Currencies in Modules](./links-to-other-modules/page.mdx): Other commerce modules use currency codes in their data models or operations. Use the Currency Module to retrieve a currency code and its details.
---
## How to Use the Currency Module
In your Medusa application, you build flows around commerce modules. A flow is built as a [Workflow](!docs!/learn/fundamentals/workflows), which is a special function composed of a series of steps that guarantees data consistency and reliable roll-back mechanism.
You can build custom workflows and steps. You can also re-use Medusa's workflows and steps, which are provided by the `@medusajs/medusa/core-flows` package.
For example:
<CodeTabs groupId="resource-type">
<CodeTab label="Workflow Step" value="workflow-step">
export const highlights = [
["13", "Modules.CURRENCY", "Resolve the module in a step."]
]
```ts title="src/workflows/hello-world/step1.ts"
import { createStep } from "@medusajs/framework/workflows-sdk"
```ts title="src/workflows/retrieve-price-with-currency.ts" highlights={highlights}
import {
createWorkflow,
WorkflowResponse,
createStep,
StepResponse,
transform,
} from "@medusajs/framework/workflows-sdk"
import { Modules } from "@medusajs/framework/utils"
const step1 = createStep("step-1", async (_, { container }) => {
const currencyModuleService = container.resolve(
Modules.CURRENCY
)
const retrieveCurrencyStep = createStep(
"retrieve-currency",
async ({}, { container }) => {
const currencyModuleService = container.resolve(Modules.CURRENCY)
const currencies = await currencyModuleService.listCurrencies()
})
const currency = await currencyModuleService
.retrieveCurrency("usd")
return new StepResponse({ currency })
}
)
type Input = {
price: number
}
export const retrievePriceWithCurrency = createWorkflow(
"create-currency",
(input: Input) => {
const { currency } = retrieveCurrencyStep()
const formattedPrice = transform({
input,
currency,
}, (data) => {
return `${data.currency.symbol}${data.input.price}`
})
return new WorkflowResponse({
formattedPrice,
})
}
)
```
</CodeTab>
<CodeTab label="API Route" value="api-route">
You can then execute the workflow in your custom API routes, scheduled jobs, or subscribers:
```ts title="src/api/store/custom/route.ts"
import { MedusaRequest, MedusaResponse } from "@medusajs/framework/http"
import { Modules } from "@medusajs/framework/utils"
<CodeTabs group="resource-types">
<CodeTab label="API Route" value="api-route">
```ts title="src/api/workflow/route.ts" highlights={[["11"], ["12"], ["13"], ["14"]]} collapsibleLines="1-6" expandButtonLabel="Show Imports"
import type {
MedusaRequest,
MedusaResponse,
} from "@medusajs/framework/http"
import { retrievePriceWithCurrency } from "../../workflows/retrieve-price-with-currency"
export async function GET(
req: MedusaRequest,
res: MedusaResponse
): Promise<void> {
const currencyModuleService = req.scope.resolve(
Modules.CURRENCY
)
) {
const { result } = await retrievePriceWithCurrency(req.scope)
.run({
price: 10,
})
res.json({
currencies: await currencyModuleService.listCurrencies(),
})
res.send(result)
}
```
</CodeTab>
<CodeTab label="Subscriber" value="subscribers">
<CodeTab label="Subscriber" value="subscriber">
```ts title="src/subscribers/user-created.ts" highlights={[["11"], ["12"], ["13"], ["14"]]} collapsibleLines="1-6" expandButtonLabel="Show Imports"
import {
type SubscriberConfig,
type SubscriberArgs,
} from "@medusajs/framework"
import { retrievePriceWithCurrency } from "../workflows/retrieve-price-with-currency"
```ts title="src/subscribers/custom-handler.ts"
import { SubscriberArgs } from "@medusajs/framework"
import { Modules } from "@medusajs/framework/utils"
export default async function handleUserCreated({
event: { data },
container,
}: SubscriberArgs<{ id: string }>) {
const { result } = await retrievePriceWithCurrency(container)
.run({
price: 10,
})
export default async function subscriberHandler({ container }: SubscriberArgs) {
const currencyModuleService = container.resolve(
Modules.CURRENCY
)
console.log(result)
}
const currencies = await currencyModuleService.listCurrencies()
export const config: SubscriberConfig = {
event: "user.created",
}
```
</CodeTab>
<CodeTab label="Scheduled Job" value="scheduled-job">
```ts title="src/jobs/run-daily.ts" highlights={[["7"], ["8"], ["9"], ["10"]]}
import { MedusaContainer } from "@medusajs/framework/types"
import { retrievePriceWithCurrency } from "../workflows/retrieve-price-with-currency"
export default async function myCustomJob(
container: MedusaContainer
) {
const { result } = await retrievePriceWithCurrency(container)
.run({
price: 10,
})
console.log(result)
}
export const config = {
name: "run-once-a-day",
schedule: `0 0 * * *`,
}
```
</CodeTab>
</CodeTabs>
Learn more about workflows in [this documentation](!docs!/learn/fundamentals/workflows).
---
## Features
### Currency Retrieval
List and retrieve currencies stored in your application.
```ts
const currency = await currencyModuleService.retrieveCurrency("usd")
```
### Support Currencies in Modules
Other commerce modules use currency codes in their data models or operations. Use the Currency Module to retrieve a currency code and its details.
An example with the Region Module:
```ts
const region = await regionModuleService.retrieveRegion("reg_123")
const currency = await currencyModuleService.retrieveCurrency(
region.currency_code
)
```
<CommerceModuleSections name="Currency" />