docs: fixes and changes based on latest updates (#7322)
* docs: changes based on DX changes * remove fields no longer needed * remove unnecessary parameters * fixes to authenticate middleware usage * add highlight to migrations config * change configuration to http * added missing remote link docs * fix name in sidebar * added notification module docs + updated file module docs * add vale exceptions * fix vale errors * added docs on custom cli scripts
This commit is contained in:
Shahed Nasser
@@ -0,0 +1,80 @@
|
||||
import { Table } from "docs-ui"
|
||||
|
||||
export const metadata = {
|
||||
title: `Local Notification Provider Module`,
|
||||
}
|
||||
|
||||
# {metadata.title}
|
||||
|
||||
The Local Notification Provider Module simulates sending a notification, but only logs the notification's details in the terminal. This is useful for development.
|
||||
|
||||
---
|
||||
|
||||
## Install the Local Notification Module
|
||||
|
||||
To install the Local Notification Provider Module, run the following command in the directory of your Medusa application:
|
||||
|
||||
```bash npm2yarn
|
||||
npm install @medusajs/notification-local
|
||||
```
|
||||
|
||||
Next, add the module into the `providers` array of the Notification Module:
|
||||
|
||||
<Note>
|
||||
|
||||
Only one provider can be defined for a channel.
|
||||
|
||||
</Note>
|
||||
|
||||
```js title="medusa-config.js"
|
||||
module.exports = {
|
||||
// ...
|
||||
modules: {
|
||||
// ...
|
||||
[Modules.NOTIFICATION]: {
|
||||
resolve: "@medusajs/notification",
|
||||
options: {
|
||||
providers: [
|
||||
// ...
|
||||
{
|
||||
resolve: "@medusajs/notification-local",
|
||||
options: {
|
||||
config: {
|
||||
local: {
|
||||
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,66 @@
|
||||
import { ChildDocs } from "docs-ui"
|
||||
|
||||
export const metadata = {
|
||||
title: `Notification Provider Modules`,
|
||||
}
|
||||
|
||||
# {metadata.title}
|
||||
|
||||
A Notification Module exposes the functionalities to send a notification to a customer or user. For example, sending an order confirmation email.
|
||||
|
||||
You can resolve the Notification Module and send notifications in API routes, subscribers, or other resources.
|
||||
|
||||
---
|
||||
|
||||
## What is a Notification Provider Module?
|
||||
|
||||
A notification provider module implements the logic of sending the notification. It either integrates a third-party service or uses custom logic to send the notification.
|
||||
|
||||
By default, Medusa uses the Local Notification Module 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 Provider Module.
|
||||
|
||||
<ChildDocs type="item" filters={["Guides"]} onlyTopLevel={true} />
|
||||
|
||||
---
|
||||
|
||||
## Notification Provider Module Channels
|
||||
|
||||
When you send a notification, you specify the channel to send it through, such as `email` or `sms`. Each provider defined in the Notification Module's `providers` option has a `channels` option specifying which channels it can be used in. Only one provider can be setup for each channel.
|
||||
|
||||
For example:
|
||||
|
||||
```js title="medusa-config.js" highlights={[["15"]]}
|
||||
module.exports = {
|
||||
// ...
|
||||
modules: {
|
||||
// ...
|
||||
[Modules.NOTIFICATION]: {
|
||||
resolve: "@medusajs/notification",
|
||||
options: {
|
||||
providers: [
|
||||
// ...
|
||||
{
|
||||
resolve: "@medusajs/notification-local",
|
||||
options: {
|
||||
config: {
|
||||
local: {
|
||||
channels: ["email"]
|
||||
},
|
||||
},
|
||||
},
|
||||
},
|
||||
],
|
||||
},
|
||||
},
|
||||
},
|
||||
}
|
||||
```
|
||||
|
||||
The `channels` option is an array of strings indicating the channels this provider is used for.
|
||||
|
||||
---
|
||||
|
||||
## Create a Notification Provider Module
|
||||
|
||||
To create a notification provider module, refer to [this guide](/references/notification-provider-module).
|
||||
@@ -0,0 +1,86 @@
|
||||
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."],
|
||||
["17", "create", "Create the notification to be sent."],
|
||||
["19", '"email"', "Use the provider module defined for the `email` channel to send an email."],
|
||||
["20", '"product-created"', "The ID of the template defined in the third-party service, such as SendGrid."],
|
||||
["21", "data", "The data to pass to the template defined in the third-party service."]
|
||||
]
|
||||
|
||||
```ts title="src/subscribers/product-created.ts" highlights={highlights}
|
||||
import type {
|
||||
SubscriberArgs,
|
||||
SubscriberConfig,
|
||||
} from "@medusajs/medusa"
|
||||
import { ModuleRegistrationName } from "@medusajs/modules-sdk"
|
||||
import { INotificationModuleService } from "@medusajs/types"
|
||||
|
||||
export default async function productCreateHandler({
|
||||
data,
|
||||
container
|
||||
}: SubscriberArgs<{ id: string }>) {
|
||||
const notificationModuleService: INotificationModuleService =
|
||||
container.resolve(
|
||||
ModuleRegistrationName.NOTIFICATION
|
||||
)
|
||||
|
||||
await notificationModuleService.create({
|
||||
to: "shahednasser@gmail.com",
|
||||
channel: "email",
|
||||
template: "product-created",
|
||||
data: "data" in data ? data.data : 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 provider module 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"
|
||||
/>
|
||||
|
||||
{/* TODO add once reference for type once generated */}
|
||||
|
||||
{/* For a full list of properties accepted, refer to [this guide](/references/notification-provider-module#create). */}
|
||||
@@ -0,0 +1,192 @@
|
||||
import { Table } from "docs-ui"
|
||||
|
||||
export const metadata = {
|
||||
title: `SendGrid Notification Provider Module`,
|
||||
}
|
||||
|
||||
# {metadata.title}
|
||||
|
||||
The SendGrid Notification Provider Module integrates [SendGrid](https://sendgrid.com) to send emails to users and customers.
|
||||
|
||||
---
|
||||
|
||||
## Install the SendGrid Notification Module
|
||||
|
||||
<Note type="check">
|
||||
|
||||
- [SendGrid account](https://signup.sendgrid.com)
|
||||
- [Setup SendGrid single sender](https://docs.sendgrid.com/ui/sending-email/sender-verification)
|
||||
- [SendGrid API Key](https://docs.sendgrid.com/ui/account-and-settings/api-keys)
|
||||
|
||||
</Note>
|
||||
|
||||
To install the SendGrid Notification Provider Module, run the following command in the directory of your Medusa application:
|
||||
|
||||
```bash npm2yarn
|
||||
npm install @medusajs/notification-sendgrid
|
||||
```
|
||||
|
||||
Next, add the module into the `providers` array of the Notification Module:
|
||||
|
||||
<Note>
|
||||
|
||||
Only one provider can be defined for a channel.
|
||||
|
||||
</Note>
|
||||
|
||||
```js title="medusa-config.js"
|
||||
module.exports = {
|
||||
// ...
|
||||
modules: {
|
||||
// ...
|
||||
[Modules.NOTIFICATION]: {
|
||||
resolve: "@medusajs/notification",
|
||||
options: {
|
||||
providers: [
|
||||
// ...
|
||||
{
|
||||
resolve: "@medusajs/notification-sendgrid",
|
||||
options: {
|
||||
config: {
|
||||
sendgrid: {
|
||||
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 = [
|
||||
["12", "notificationModuleService", "Resolve the Notification Module."],
|
||||
["17", "create", "Create the notification to be sent."],
|
||||
["19", '"email"', "By specifying the `email` channel, SendGrid will be used to send the notification."],
|
||||
["20", '"product-created"', "The ID of the template defined in SendGrid."],
|
||||
["21", "data", "The data to pass to the template defined in SendGrid."]
|
||||
]
|
||||
|
||||
```ts title="src/subscribers/product-created.ts" highlights={highlights}
|
||||
import type {
|
||||
SubscriberArgs,
|
||||
SubscriberConfig,
|
||||
} from "@medusajs/medusa"
|
||||
import { ModuleRegistrationName } from "@medusajs/modules-sdk"
|
||||
import { INotificationModuleService } from "@medusajs/types"
|
||||
|
||||
export default async function productCreateHandler({
|
||||
data,
|
||||
container
|
||||
}: SubscriberArgs<{ id: string }>) {
|
||||
const notificationModuleService: INotificationModuleService =
|
||||
container.resolve(
|
||||
ModuleRegistrationName.NOTIFICATION
|
||||
)
|
||||
|
||||
await notificationModuleService.create({
|
||||
to: "test@gmail.com",
|
||||
channel: "email",
|
||||
template: "product-created",
|
||||
data: "data" in data ? data.data : data
|
||||
})
|
||||
}
|
||||
|
||||
export const config: SubscriberConfig = {
|
||||
event: "product.created",
|
||||
}
|
||||
```
|
||||
|
||||
In this subscriber:
|
||||
|
||||
- Resolve the Notification Module's main service.
|
||||
- Use the `create` method of the main service to create a notification to be sent to the specified email.
|
||||
- By specifying the `email` channel, the SendGrid Notification Provider Module is used to send the notification.
|
||||
- The `template` property of the `create` 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.
|
||||
|
||||
Then, start the Medusa application:
|
||||
|
||||
```bash npm2yarn
|
||||
npm run dev
|
||||
```
|
||||
|
||||
{/* TODO add links */}
|
||||
|
||||
And create a product either using the [API route](!api!/api/admin#products_postproducts) or the Medusa Admin. This runs the subscriber and sends an email using SendGrid.
|
||||
Reference in New Issue
Block a user