docs: rename Architectural Modules to Infrastructure Modules (#12212)
* docs: rename Architectural Modules to Infrastructure Modules * generate again
This commit is contained in:
Shahed Nasser authored and 
GitHub committed
1 parent
8618e6ee38
commit
eb73bdb478
149 files changed
+12165
-12145
No files matched your search
@@ -0,0 +1,80 @@
|
||||
import { Table } from "docs-ui"
|
||||
|
||||
export const metadata = {
|
||||
title: `Local Notification Module Provider`,
|
||||
}
|
||||
|
||||
# {metadata.title}
|
||||
|
||||
The Local Notification Module Provider simulates sending a notification, but only logs the notification's details in the terminal. This is useful for development.
|
||||
|
||||
---
|
||||
|
||||
## Register the Local Notification Module
|
||||
|
||||
<Note>
|
||||
|
||||
The Local Notification Module Provider is registered by default in your application. It's configured to run on the `feed` channel.
|
||||
|
||||
</Note>
|
||||
|
||||
Add the module into the `providers` array of the Notification Module:
|
||||
|
||||
<Note>
|
||||
|
||||
Only one provider can be defined for a channel.
|
||||
|
||||
</Note>
|
||||
|
||||
```ts title="medusa-config.ts"
|
||||
import { Modules } from "@medusajs/framework/utils"
|
||||
|
||||
// ...
|
||||
|
||||
module.exports = defineConfig({
|
||||
// ...
|
||||
modules: [
|
||||
{
|
||||
resolve: "@medusajs/medusa/notification",
|
||||
options: {
|
||||
providers: [
|
||||
// ...
|
||||
{
|
||||
resolve: "@medusajs/medusa/notification-local",
|
||||
id: "local",
|
||||
options: {
|
||||
channels: ["email"],
|
||||
},
|
||||
},
|
||||
],
|
||||
},
|
||||
},
|
||||
],
|
||||
})
|
||||
```
|
||||
|
||||
### Local Notification Module Options
|
||||
|
||||
<Table>
|
||||
<Table.Header>
|
||||
<Table.Row>
|
||||
<Table.HeaderCell>Option</Table.HeaderCell>
|
||||
<Table.HeaderCell>Description</Table.HeaderCell>
|
||||
</Table.Row>
|
||||
</Table.Header>
|
||||
<Table.Body>
|
||||
<Table.Row>
|
||||
<Table.Cell>
|
||||
|
||||
`channels`
|
||||
|
||||
</Table.Cell>
|
||||
<Table.Cell>
|
||||
|
||||
The channels this notification module is used to send notifications for. While the local notification module doesn't actually send the notification,
|
||||
it's important to specify its channels to make sure it's used when a notification for that channel is created.
|
||||
|
||||
</Table.Cell>
|
||||
</Table.Row>
|
||||
</Table.Body>
|
||||
</Table>
|
||||
@@ -0,0 +1,131 @@
|
||||
import { CardList } from "docs-ui"
|
||||
|
||||
export const metadata = {
|
||||
title: `Notification Module`,
|
||||
}
|
||||
|
||||
# {metadata.title}
|
||||
|
||||
In this document, you'll learn about the Notification Module and its providers.
|
||||
|
||||
## What is the Notification Module?
|
||||
|
||||
The Notification Module exposes the functionalities to send a notification to a customer or user. For example, sending an order confirmation email. Medusa uses the Notification Module in its core commerce features for notification operations, and you an use it in your custom features as well.
|
||||
|
||||
---
|
||||
|
||||
## How to Use the Notification Module?
|
||||
|
||||
You can use the Notification Module as part of the [workflows](!docs!/learn/fundamentals/workflows) you build for your custom features. A workflow is a special function composed of a series of steps that guarantees data consistency and reliable roll-back mechanism.
|
||||
|
||||
In a step of your workflow, you can resolve the Notification Module's service and use its methods to send notifications.
|
||||
|
||||
For example:
|
||||
|
||||
```ts
|
||||
import { Modules } from "@medusajs/framework/utils"
|
||||
import {
|
||||
createStep,
|
||||
createWorkflow,
|
||||
} from "@medusajs/framework/workflows-sdk"
|
||||
|
||||
const step1 = createStep(
|
||||
"step-1",
|
||||
async ({}, { container }) => {
|
||||
const notificationModuleService = container.resolve(
|
||||
Modules.NOTIFICATION
|
||||
)
|
||||
|
||||
await notificationModuleService.createNotifications({
|
||||
to: "customer@gmail.com",
|
||||
channel: "email",
|
||||
template: "product-created",
|
||||
data,
|
||||
})
|
||||
}
|
||||
)
|
||||
|
||||
export const workflow = createWorkflow(
|
||||
"workflow-1",
|
||||
() => {
|
||||
step1()
|
||||
}
|
||||
)
|
||||
```
|
||||
|
||||
In the example above, you create a workflow that has a step. In the step, you resolve the service of the Notification Module from the [Medusa container](!docs!/learn/fundamentals/medusa-container).
|
||||
|
||||
Then, you use the `createNotifications` method of the Notification Module to send an email notification.
|
||||
|
||||
Find a full example of sending a notification in the [Send Notification guide](./send-notification/page.mdx).
|
||||
|
||||
---
|
||||
|
||||
## What is a Notification Module Provider?
|
||||
|
||||
A Notification Module Provider implements the underlying logic of sending notification. It either integrates a third-party service or uses custom logic to send the notification.
|
||||
|
||||
By default, Medusa uses the [Local Notification Module](./local/page.mdx) which only simulates sending the notification by logging a message in the terminal.
|
||||
|
||||
Medusa provides other Notification Modules that actually send notifications, such as the [SendGrid Notification Module Provider](./send-notification/page.mdx). You can also [Create a Notification Module Provider](/references/notification-provider-module).
|
||||
|
||||
<CardList
|
||||
items={[
|
||||
{
|
||||
title: "Local",
|
||||
href: "/infrastructure-modules/notification/local",
|
||||
badge: {
|
||||
variant: "neutral",
|
||||
children: "For Development"
|
||||
}
|
||||
},
|
||||
{
|
||||
title: "SendGrid",
|
||||
href: "/infrastructure-modules/notification/sendgrid",
|
||||
badge: {
|
||||
variant: "green",
|
||||
children: "For Production"
|
||||
}
|
||||
}
|
||||
]}
|
||||
/>
|
||||
|
||||
---
|
||||
|
||||
## Notification Module Provider Channels
|
||||
|
||||
When you send a notification, you specify the channel to send it through, such as `email` or `sms`.
|
||||
|
||||
You register providers of the Notification Module in `medusa-config.ts`. For each provider, you pass a `channels` option specifying which channels the provider can be used in. Only one provider can be setup for each channel.
|
||||
|
||||
For example:
|
||||
|
||||
```ts title="medusa-config.ts" highlights={[["19"]]}
|
||||
import { Modules } from "@medusajs/framework/utils"
|
||||
|
||||
// ...
|
||||
|
||||
module.exports = {
|
||||
// ...
|
||||
modules: [
|
||||
// ...
|
||||
{
|
||||
resolve: "@medusajs/medusa/notification",
|
||||
options: {
|
||||
providers: [
|
||||
// ...
|
||||
{
|
||||
resolve: "@medusajs/medusa/notification-local",
|
||||
id: "notification",
|
||||
options: {
|
||||
channels: ["email"],
|
||||
},
|
||||
},
|
||||
],
|
||||
},
|
||||
},
|
||||
],
|
||||
}
|
||||
```
|
||||
|
||||
The `channels` option is an array of strings indicating the channels this provider is used for.
|
||||
+105
@@ -0,0 +1,105 @@
|
||||
---
|
||||
sidebar_label: "Send Notification"
|
||||
tags:
|
||||
- notification
|
||||
- how to
|
||||
- server
|
||||
---
|
||||
|
||||
import { TypeList } from "docs-ui"
|
||||
|
||||
export const metadata = {
|
||||
title: `Send Notification with the Notification Module`,
|
||||
}
|
||||
|
||||
# {metadata.title}
|
||||
|
||||
In this guide, you'll learn how to send a notification using the Notification Module.
|
||||
|
||||
## Use the Create Method
|
||||
|
||||
In your resource, such as a subscriber, resolve the Notification Module's main service and use its `create` method:
|
||||
|
||||
export const highlights = [
|
||||
["12", "notificationModuleService", "Resolve the Notification Module."],
|
||||
["15", "create", "Create the notification to be sent."],
|
||||
[
|
||||
"17",
|
||||
'"email"',
|
||||
"Use the module provider defined for the `email` channel to send an email.",
|
||||
],
|
||||
[
|
||||
"18",
|
||||
'"product-created"',
|
||||
"The ID of the template defined in the third-party service, such as SendGrid.",
|
||||
],
|
||||
[
|
||||
"19",
|
||||
"data",
|
||||
"The data to pass to the template defined in the third-party service.",
|
||||
],
|
||||
]
|
||||
|
||||
```ts title="src/subscribers/product-created.ts" highlights={highlights} collapsibleLines="1-7" expandButtonLabel="Show Imports"
|
||||
import type {
|
||||
SubscriberArgs,
|
||||
SubscriberConfig,
|
||||
} from "@medusajs/framework"
|
||||
import { Modules } from "@medusajs/framework/utils"
|
||||
import { INotificationModuleService } from "@medusajs/framework/types"
|
||||
|
||||
export default async function productCreateHandler({
|
||||
event: { data },
|
||||
container,
|
||||
}: SubscriberArgs<{ id: string }>) {
|
||||
const notificationModuleService: INotificationModuleService =
|
||||
container.resolve(Modules.NOTIFICATION)
|
||||
|
||||
await notificationModuleService.createNotifications({
|
||||
to: "shahednasser@gmail.com",
|
||||
channel: "email",
|
||||
template: "product-created",
|
||||
data,
|
||||
})
|
||||
}
|
||||
|
||||
export const config: SubscriberConfig = {
|
||||
event: "product.created",
|
||||
}
|
||||
```
|
||||
|
||||
The `create` method accepts an object or an array of objects having the following properties:
|
||||
|
||||
<TypeList
|
||||
types={[
|
||||
{
|
||||
name: "to",
|
||||
type: "`string`",
|
||||
description:
|
||||
"The destination to send the notification to. When sending an email, it'll be the email address. When sending an SMS, it'll be the phone number.",
|
||||
optional: false,
|
||||
},
|
||||
{
|
||||
name: "channel",
|
||||
type: "`string`",
|
||||
description:
|
||||
"The channel to send the notification through. For example, `email` or `sms`. The module provider defined for that channel will be used to send the notification.",
|
||||
optional: false,
|
||||
},
|
||||
{
|
||||
name: "template",
|
||||
type: "`string`",
|
||||
description:
|
||||
"The ID of the template used for the notification. This is useful for providers like SendGrid, where you define templates within SendGrid and use their IDs here.",
|
||||
optional: false,
|
||||
},
|
||||
{
|
||||
name: "data",
|
||||
type: "`Record<string, unknown>`",
|
||||
description: "The data to pass along to the template, if necessary.",
|
||||
},
|
||||
]}
|
||||
sectionTitle="Use the Create Method"
|
||||
/>
|
||||
|
||||
For a full list of properties accepted, refer to [this guide](/references/notification-provider-module#create).
|
||||
@@ -0,0 +1,176 @@
|
||||
import { Table, Prerequisites } from "docs-ui"
|
||||
|
||||
export const metadata = {
|
||||
title: `SendGrid Notification Module Provider`,
|
||||
}
|
||||
|
||||
# {metadata.title}
|
||||
|
||||
The SendGrid Notification Module Provider integrates [SendGrid](https://sendgrid.com) to send emails to users and customers.
|
||||
|
||||
---
|
||||
|
||||
## Register the SendGrid Notification Module
|
||||
|
||||
<Prerequisites
|
||||
items={[
|
||||
{
|
||||
text: "SendGrid account",
|
||||
link: "https://signup.sendgrid.com",
|
||||
},
|
||||
{
|
||||
text: "Setup SendGrid single sender",
|
||||
link: "https://docs.sendgrid.com/ui/sending-email/sender-verification",
|
||||
},
|
||||
{
|
||||
text: "SendGrid API Key",
|
||||
link: "https://docs.sendgrid.com/ui/account-and-settings/api-keys",
|
||||
},
|
||||
]}
|
||||
/>
|
||||
|
||||
Add the module into the `providers` array of the Notification Module:
|
||||
|
||||
<Note>
|
||||
|
||||
Only one provider can be defined for a channel.
|
||||
|
||||
</Note>
|
||||
|
||||
```ts title="medusa-config.ts"
|
||||
import { Modules } from "@medusajs/framework/utils"
|
||||
|
||||
// ...
|
||||
|
||||
module.exports = defineConfig({
|
||||
// ...
|
||||
modules: [
|
||||
{
|
||||
resolve: "@medusajs/medusa/notification",
|
||||
options: {
|
||||
providers: [
|
||||
// ...
|
||||
{
|
||||
resolve: "@medusajs/medusa/notification-sendgrid",
|
||||
id: "sendgrid",
|
||||
options: {
|
||||
channels: ["email"],
|
||||
api_key: process.env.SENDGRID_API_KEY,
|
||||
from: process.env.SENDGRID_FROM,
|
||||
},
|
||||
},
|
||||
],
|
||||
},
|
||||
},
|
||||
],
|
||||
})
|
||||
```
|
||||
|
||||
### Environment Variables
|
||||
|
||||
Make sure to add the following environment variables:
|
||||
|
||||
```bash
|
||||
SENDGRID_API_KEY=<YOUR_SENDGRID_API_KEY>
|
||||
SENDGRID_FROM=<YOUR_SENDGRID_FROM>
|
||||
```
|
||||
|
||||
### SendGrid Notification Module Options
|
||||
|
||||
<Table>
|
||||
<Table.Header>
|
||||
<Table.Row>
|
||||
<Table.HeaderCell>Option</Table.HeaderCell>
|
||||
<Table.HeaderCell>Description</Table.HeaderCell>
|
||||
</Table.Row>
|
||||
</Table.Header>
|
||||
<Table.Body>
|
||||
<Table.Row>
|
||||
<Table.Cell>`channels`</Table.Cell>
|
||||
<Table.Cell>
|
||||
The channels this notification module is used to send notifications for.
|
||||
Only one provider can be defined for a channel.
|
||||
</Table.Cell>
|
||||
</Table.Row>
|
||||
<Table.Row>
|
||||
<Table.Cell>`api_key`</Table.Cell>
|
||||
<Table.Cell>The SendGrid API key.</Table.Cell>
|
||||
</Table.Row>
|
||||
<Table.Row>
|
||||
<Table.Cell>`from`</Table.Cell>
|
||||
<Table.Cell>The SendGrid from email.</Table.Cell>
|
||||
</Table.Row>
|
||||
</Table.Body>
|
||||
</Table>
|
||||
|
||||
## SendGrid Templates
|
||||
|
||||
When you send a notification, you must specify the ID of the template to use in SendGrid.
|
||||
|
||||
Refer to [this SendGrid documentation guide](https://docs.sendgrid.com/ui/sending-email/how-to-send-an-email-with-dynamic-templates) on how to create templates for your different email types.
|
||||
|
||||
---
|
||||
|
||||
## Test out the Module
|
||||
|
||||
To test the module out, create a simple subscriber at `src/subscribers/product-created.ts` with the following content:
|
||||
|
||||
export const highlights = [
|
||||
["11", "notificationModuleService", "Resolve the Notification Module."],
|
||||
["13", "createNotifications", "Create the notification to be sent."],
|
||||
[
|
||||
"15",
|
||||
'"email"',
|
||||
"By specifying the `email` channel, SendGrid will be used to send the notification.",
|
||||
],
|
||||
["16", '"product-created"', "The ID of the template defined in SendGrid."],
|
||||
["17", "data", "The data to pass to the template defined in SendGrid."],
|
||||
]
|
||||
|
||||
```ts title="src/subscribers/product-created.ts" highlights={highlights} collapsibleLines="1-7" expandButtonLabel="Show Imports"
|
||||
import type {
|
||||
SubscriberArgs,
|
||||
SubscriberConfig,
|
||||
} from "@medusajs/framework"
|
||||
import { Modules } from "@medusajs/framework/utils"
|
||||
|
||||
export default async function productCreateHandler({
|
||||
event: { data },
|
||||
container,
|
||||
}: SubscriberArgs<{ id: string }>) {
|
||||
const notificationModuleService = container.resolve(Modules.NOTIFICATION)
|
||||
const productModuleService = container.resolve(Modules.PRODUCT)
|
||||
|
||||
const product = await productModuleService.retrieveProduct(data.id)
|
||||
|
||||
await notificationModuleService.createNotifications({
|
||||
to: "test@gmail.com",
|
||||
channel: "email",
|
||||
template: "product-created",
|
||||
data: {
|
||||
product_title: product.title,
|
||||
product_image: product.images[0]?.url,
|
||||
},
|
||||
})
|
||||
}
|
||||
|
||||
export const config: SubscriberConfig = {
|
||||
event: "product.created",
|
||||
}
|
||||
```
|
||||
|
||||
In this subscriber, you:
|
||||
|
||||
- Resolve the Notification and Product Modules' main services from the [Medusa container](!docs!/learn/fundamentals/medusa-container).
|
||||
- Retrieve the product's details to pass them to the template in SendGrid.
|
||||
- Use the `createNotifications` method of the Notification Module's main service to create a notification to be sent to the specified email. By specifying the `email` channel, the SendGrid Notification Module Provider is used to send the notification.
|
||||
- The `template` property of the `createNotifications` method's parameter specifies the ID of the template defined in SendGrid.
|
||||
- The `data` property allows you to pass data to the template in SendGrid. For example, the product's title and image.
|
||||
|
||||
Then, start the Medusa application:
|
||||
|
||||
```bash npm2yarn
|
||||
npm run dev
|
||||
```
|
||||
|
||||
And create a product either using the [API route](!api!/admin#products_postproducts) or the [Medusa Admin](!user-guide!/products/create). This runs the subscriber and sends an email using SendGrid.
|
||||
Reference in new issue
Block a user