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

docs: improved commerce modules [5/5] (#9592)

Browse Source 
- Improve remaining commerce modules
- Other: add a note about using methods of the modules' main services.
This commit is contained in:
Shahed Nasser authored and GitHub committed 2024-10-16 10:25:21 +00:00
1 parent 6e856d3156
commit eed88c95ec
42 files changed
+594 -582
Download Patch File Download Diff File Expand all files Collapse all files

No files matched your search

www/apps/resources/app/commerce-modules/sales-channel/examples/page.mdx
+26 -25
View File
@@ -8,21 +8,26 @@ export const metadata = {
In this guide, you’ll find common examples of how you can use the Sales Channel Module in your application.
<Note>
You should only use the Sales Channel Module's main service when implementing complex customizations. For common cases, check out [available workflows instead](../../../medusa-workflows-reference/page.mdx).
</Note>
## Create a Sales Channel
<CodeTabs groupId="app-type">
<CodeTab label="Medusa API Router" value="medusa">
```ts
import { MedusaRequest, MedusaResponse } from "@medusajs/framework/http"
import { ISalesChannelModuleService } from "@medusajs/framework/types"
import { Modules } from "@medusajs/framework/utils"
```ts
import { MedusaRequest, MedusaResponse } from "@medusajs/framework/http"
import { Modules } from "@medusajs/framework/utils"
export async function POST(
request: MedusaRequest,
res: MedusaResponse
): Promise<void> {
const salesChannelModuleService: ISalesChannelModuleService =
const salesChannelModuleService =
request.scope.resolve(Modules.SALES_CHANNEL)
const salesChannel = await salesChannelModuleService.createSalesChannels({
@@ -64,16 +69,15 @@ export async function POST(request: Request) {
<CodeTabs groupId="app-type">
<CodeTab label="Medusa API Router" value="medusa">
```ts
import { MedusaRequest, MedusaResponse } from "@medusajs/framework/http"
import { ISalesChannelModuleService } from "@medusajs/framework/types"
import { Modules } from "@medusajs/framework/utils"
```ts
import { MedusaRequest, MedusaResponse } from "@medusajs/framework/http"
import { Modules } from "@medusajs/framework/utils"
export async function GET(
request: MedusaRequest,
res: MedusaResponse
): Promise<void> {
const salesChannelModuleService: ISalesChannelModuleService =
const salesChannelModuleService =
request.scope.resolve(Modules.SALES_CHANNEL)
res.json({
@@ -109,16 +113,15 @@ export async function GET(request: Request) {
<CodeTabs groupId="app-type">
<CodeTab label="Medusa API Router" value="medusa">
```ts
import { MedusaRequest, MedusaResponse } from "@medusajs/framework/http"
import { ISalesChannelModuleService } from "@medusajs/framework/types"
import { Modules } from "@medusajs/framework/utils"
```ts
import { MedusaRequest, MedusaResponse } from "@medusajs/framework/http"
import { Modules } from "@medusajs/framework/utils"
export async function GET(
request: MedusaRequest,
res: MedusaResponse
): Promise<void> {
const salesChannelModuleService: ISalesChannelModuleService =
const salesChannelModuleService =
request.scope.resolve(Modules.SALES_CHANNEL)
const salesChannel = await salesChannelModuleService.retrieveSalesChannel(
@@ -160,16 +163,15 @@ export async function GET(request: Request) {
<CodeTabs groupId="app-type">
<CodeTab label="Medusa API Router" value="medusa">
```ts
import { MedusaRequest, MedusaResponse } from "@medusajs/framework/http"
import { ISalesChannelModuleService } from "@medusajs/framework/types"
import { Modules } from "@medusajs/framework/utils"
```ts
import { MedusaRequest, MedusaResponse } from "@medusajs/framework/http"
import { Modules } from "@medusajs/framework/utils"
export async function POST(
request: MedusaRequest,
res: MedusaResponse
): Promise<void> {
const salesChannelModuleService: ISalesChannelModuleService =
const salesChannelModuleService =
request.scope.resolve(Modules.SALES_CHANNEL)
const salesChannel = await salesChannelModuleService.updateSalesChannels({
@@ -213,16 +215,15 @@ export async function POST(request: Request) {
<CodeTabs groupId="app-type">
<CodeTab label="Medusa API Router" value="medusa">
```ts
import { MedusaRequest, MedusaResponse } from "@medusajs/framework/http"
import { ISalesChannelModuleService } from "@medusajs/framework/types"
import { Modules } from "@medusajs/framework/utils"
```ts
import { MedusaRequest, MedusaResponse } from "@medusajs/framework/http"
import { Modules } from "@medusajs/framework/utils"
export async function DELETE(
request: MedusaRequest,
res: MedusaResponse
): Promise<void> {
const salesChannelModuleService: ISalesChannelModuleService =
const salesChannelModuleService =
request.scope.resolve(Modules.SALES_CHANNEL)
await salesChannelModuleService.deleteSalesChannels("sc_123")
www/apps/resources/app/commerce-modules/sales-channel/links-to-other-modules/page.mdx
+35
View File
@@ -0,0 +1,35 @@
export const metadata = {
title: `Links between Sales Channel Module and Other Modules`,
}
# {metadata.title}
This document showcases the module links defined between the Sales Channel Module and other commerce modules.
## API Key Module
A publishable API key allows you to easily specify the sales channel scope in a client request.
Medusa defines a link between the `ApiKey` and the `SalesChannel` data models.
![A diagram showcasing an example of how resources from the Sales Channel and API Key modules are linked](https://res.cloudinary.com/dza7lstvk/image/upload/v1709812064/Medusa%20Resources/sales-channel-api-key_zmqi2l.jpg)
---
## Product Module
A product has different availability for different sales channels. Medusa defines a link between the `Product` and the `SalesChannel` data models.
![A diagram showcasing an example of how resources from the Sales Channel and Product modules are linked](https://res.cloudinary.com/dza7lstvk/image/upload/v1709809833/Medusa%20Resources/product-sales-channel_t848ik.jpg)
A product can be available in more than one sales channel. You can retrieve only the products of a sales channel.
---
## Stock Location Module
A stock location is associated with a sales channel. This scopes inventory quantities associated with that stock location by the associated sales channel.
Medusa defines a link between the `SalesChannel` and `StockLocation` data models.
![A diagram showcasing an example of how resources from the Sales Channel and Stock Location modules are linked](https://res.cloudinary.com/dza7lstvk/image/upload/v1716796872/Medusa%20Resources/sales-channel-location_cqrih1.jpg)
www/apps/resources/app/commerce-modules/sales-channel/page.mdx
+26 -29
View File
@@ -6,7 +6,7 @@ export const metadata = {
# {metadata.title}
The Sales Channel Module is the `@medusajs/medusa/sales-channel` NPM package that provides sales-channel-related features in your Medusa and Node.js applications.
The Sales Channel Module provides sales-channel-related features in your Medusa and Node.js applications.
## How to Use Sales Channel Module's Service
@@ -15,18 +15,32 @@ You can use the Sales Channel Module's main service by resolving from the Medusa
For example:
<CodeTabs groupId="resource-type">
<CodeTab label="Workflow Step" value="workflow-step">
```ts title="src/workflows/hello-world/step1.ts"
import { createStep } from "@medusajs/framework/workflows-sdk"
import { Modules } from "@medusajs/framework/utils"
const step1 = createStep("step-1", async (_, { container }) => {
const salesChannelModuleService =
container.resolve(Modules.SALES_CHANNEL)
const salesChannels = await salesChannelModuleService.listSalesChannels()
})
```
</CodeTab>
<CodeTab label="API Route" value="api-route">
```ts title="src/api/store/custom/route.ts"
import { MedusaRequest, MedusaResponse } from "@medusajs/framework/http"
import { ISalesChannelModuleService } from "@medusajs/framework/types"
import { Modules } from "@medusajs/framework/utils"
```ts title="src/api/store/custom/route.ts"
import { MedusaRequest, MedusaResponse } from "@medusajs/framework/http"
import { Modules } from "@medusajs/framework/utils"
export async function GET(
request: MedusaRequest,
res: MedusaResponse
): Promise<void> {
const salesChannelModuleService: ISalesChannelModuleService =
const salesChannelModuleService =
request.scope.resolve(Modules.SALES_CHANNEL)
res.json({
@@ -38,33 +52,16 @@ export async function GET(
</CodeTab>
<CodeTab label="Subscriber" value="subscribers">
```ts title="src/subscribers/custom-handler.ts"
import { SubscriberArgs } from "@medusajs/framework"
import { ISalesChannelModuleService } from "@medusajs/framework/types"
import { Modules } from "@medusajs/framework/utils"
```ts title="src/subscribers/custom-handler.ts"
import { SubscriberArgs } from "@medusajs/framework"
import { Modules } from "@medusajs/framework/utils"
export default async function subscriberHandler({ container }: SubscriberArgs) {
const salesChannelModuleService: ISalesChannelModuleService =
const salesChannelModuleService =
container.resolve(Modules.SALES_CHANNEL)
const salesChannels = await salesChannelModuleService.listSalesChannels()
}
```
</CodeTab>
<CodeTab label="Workflow Step" value="workflow-step">
```ts title="src/workflows/hello-world/step1.ts"
import { createStep } from "@medusajs/framework/workflows-sdk"
import { ISalesChannelModuleService } from "@medusajs/framework/types"
import { Modules } from "@medusajs/framework/utils"
const step1 = createStep("step-1", async (_, { container }) => {
const salesChannelModuleService: ISalesChannelModuleService =
container.resolve(Modules.SALES_CHANNEL)
const salesChannels = await salesChannelModuleService.listSalesChannels()
})
```
</CodeTab>
@@ -74,7 +71,7 @@ const step1 = createStep("step-1", async (_, { container }) => {
## What's a Sales Channel?
A sales channel indicates an online or offline platform that you sell products on.
A sales channel indicates an online or offline channel that you sell products on.
Some use case examples for using a sales channel:
@@ -103,7 +100,7 @@ const salesChannels = await salesChannelModuleService.createSalesChannels([
### Product Availability
Medusa links the Product and Sales Channel modules, allowing merchants to specify a product's availability per sales channel.
Medusa uses the Product and Sales Channel modules to allow merchants to specify a product's availability per sales channel.
For example, B2B customers viewing products only see products in the B2B sales channel.
www/apps/resources/app/commerce-modules/sales-channel/publishable-api-keys/page.mdx
+5 -13
View File
@@ -8,27 +8,19 @@ export const metadata = {
In this document, you’ll learn what publishable API keys are and how to use them with sales channels.
## Without Publishable API Keys
## Publishable API Keys with Sales Channels
When using multiple sales channels, you’ll need to specify the ID of a storefront’s sales channel. This ensures that you retrieve the products available in that sales channel and associate the sales channel with the storefront’s carts and orders.
A publishable API key, provided by the API Key Module, is a client key scoped to one or more sales channels.
The [Store API routes](!api!/store) accept the sales channel’s IDs differently depending on the API route's HTTP method. Some accept it as a query parameter whereas others accept it as a request body parameter.
This approach is tedious and error-prone as your storefront scales and as you develop multiple types of storefronts.
---
## Introducing Publishable API Keys
A publishable API key, provided by the API Key Module, is a client key scoped to one or more sales channels. When passed in the header of a request, the Medusa application infers the associated sales channels.
So, instead of the approach, indicated in the previous section, of manually passing the sales channel’s ID based on the API route, you always pass the publishable API key in the header of your requests:
When sending a request to a Store API route, you must pass a publishable API key in the header of the request:
```bash
curl http://localhost:9000/store/products \
x-publishable-api-key: {your_publishable_api_key}
```
The Medusa application infers the associated sales channels and ensures that only data relevant to the sales channel are used.
---
## How to Create a Publishable API Key?
www/apps/resources/app/commerce-modules/sales-channel/relations-to-other-modules/page.mdx
-55
View File
@@ -1,55 +0,0 @@
export const metadata = {
title: `Relations between Sales Channel Module and Other Modules`,
}
# {metadata.title}
This document showcases the link modules defined between the Sales Channel Module and other commerce modules.
## API Key Module
A publishable API key allows you to easily specify the sales channel scope in a client request. Medusa defines a link module that builds a relationship between the `ApiKey` and the `SalesChannel` data models.
![A diagram showcasing an example of how resources from the Sales Channel and API Key modules are linked](https://res.cloudinary.com/dza7lstvk/image/upload/v1709812064/Medusa%20Resources/sales-channel-api-key_zmqi2l.jpg)
Using the API Key Module, you create a publishable key and associate it with a sales channel. Learn more in [this document](../publishable-api-keys/page.mdx)
---
## Cart Module
A cart is associated with the sales channel it's created in. Medusa defines a link module that builds a relationship between the `Cart` and the `SalesChannel` data models.
![A diagram showcasing an example of how data models from the Cart and Sales Channel modules are linked](https://res.cloudinary.com/dza7lstvk/image/upload/v1711538159/Medusa%20Resources/cart-sales-channel_n2oi0v.jpg)
For example, if a customer adds an item to the cart in a mobile app, the cart is associated with the mobile app's sales channel. However, if a customer adds an item to the cart in a web storefront, the cart is associated with the storefront's sales channel.
---
## Order Module
An order is associated with the sales channel it's created in. Medusa defines a link module that builds a relationship between the `Order` and the `SalesChannel` data models.
![A diagram showcasing an example of how resources from the Order and Sales Channel modules are linked](https://res.cloudinary.com/dza7lstvk/image/upload/v1712315409/Medusa%20Resources/order-sales-channel_dy72gx.jpg)
For example, if an order is created in a mobile app, it'll be associated with its sales channel. If another order is created through a POS system, it'll be associated with the POS's sales channel.
---
## Product Module
A product has different availability for different sales channels. Medusa defines a link module that builds a relationship between the `Product` and the `SalesChannel` data models.
A product can be available in more than one sales channel. Then, you can retrieve only the products of a sales channel.
![A diagram showcasing an example of how resources from the Sales Channel and Product modules are linked](https://res.cloudinary.com/dza7lstvk/image/upload/v1709809833/Medusa%20Resources/product-sales-channel_ciqj6i.jpg)
---
## Stock Location Module
A stock location is associated with a sales channel. This scopes inventory quantities associated with that stock location by the associated sales channel.
Medusa defines a link module that builds a relationship between the `SalesChannel` and `StockLocation` data models.
![A diagram showcasing an example of how resources from the Sales Channel and Stock Location modules are linked](https://res.cloudinary.com/dza7lstvk/image/upload/v1716796872/Medusa%20Resources/sales-channel-location_cqrih1.jpg)