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

docs: documentation for v1.18 (#5652)

Browse Source 
* docs: documentation for v.17.5

* fix links

* updated version number
This commit is contained in:
Shahed Nasser
2023-11-21 08:57:11 +00:00
committed by GitHub
parent adc60e519c
commit 9c7f95c3d5
36 changed files with 1499 additions and 1336 deletions
Download Patch File Download Diff File Expand all files Collapse all files
www/apps/docs/content/modules/customers/backend/send-confirmation.md
+84 -128
View File
@@ -9,7 +9,9 @@ In this document, you’ll learn how to send a confirmation email to the custome
## Overview
When a customer registers, the event `customer.created` is triggered. You can then listen to this event in a subscriber to perform an action, such as send the customer a confirmation email.
When a customer registers, the event `customer.created` is triggered. You can then listen to this event in a subscriber to perform an action, such as send the customer a confirmation email.
Alternatively, you can use subscribe a Notification Provider to the event, if the Notification Provider Service implements the logic to handle the event.
This guide will explain how to create the subscriber and how to use SendGrid to send the confirmation email. SendGrid is only used to illustrate how the process works, but you’re free to use any other notification service.
@@ -31,155 +33,73 @@ You can also find other available Notification provider plugins in the [Plugins
---
## Step 1: Create the Subscriber
## Method 1: Using a Subscriber
To subscribe to and handle an event, you must create a subscriber.
:::note
You can learn more about subscribers in the [Subscribers documentation](../../../development/events/subscribers.mdx).
:::
To subscribe to an event, you must create a [subscriber](../../../development/events/subscribers.mdx).
Create the file `src/subscribers/customer-confirmation.ts` with the following content:
```ts title=src/subscribers/customer-confirmation.ts
type InjectedDependencies = {
// TODO add necessary dependencies
import {
type SubscriberConfig,
type SubscriberArgs,
CustomerService,
} from "@medusajs/medusa"
export default async function handleCustomerCreated({
data, eventName, container, pluginOptions,
}: SubscriberArgs<Record<string, string>>) {
// TODO: handle event
}
class CustomerConfirmationSubscriber {
constructor(container: InjectedDependencies) {
// TODO subscribe to event
}
export const config: SubscriberConfig = {
event: CustomerService.Events.CREATED,
context: {
subscriberId: "customer-created-handler",
},
}
export default CustomerConfirmationSubscriber
```
You’ll be adding in the next step the necessary dependencies to the subscriber.
In this file, you export a configuration object indicating that the subscriber is listening to the `CustomerService.Events.CREATED` (or `customer.created`) event.
:::note
You can learn more about dependency injection in [this documentation](../../../development/fundamentals/dependency-injection.md).
:::
---
## Step 2: Subscribe to the Event
In this step, you’ll subscribe to the `customer.created` event to send the customer a confirmation email.
There are two ways to do this:
### Method 1: Using the NotificationService
If the notification provider you’re using already implements the logic to handle this event, you can subscribe to the event using the `NotificationService`:
```ts title=src/subscribers/customer-confirmation.ts
import { NotificationService } from "@medusajs/medusa"
type InjectedDependencies = {
notificationService: NotificationService
}
class CustomerConfirmationSubscriber {
constructor({ notificationService }: InjectedDependencies) {
notificationService.subscribe(
"customer.created",
"<NOTIFICATION_PROVIDER_IDENTIFIER>"
)
}
}
export default CustomerConfirmationSubscriber
```
Where `<NOTIFICATION_PROVIDER_IDENTIFIER>` is the identifier for your notification provider.
:::note
You can learn more about handling events with the Notification Service using [this documentation](../../../development/notification/create-notification-provider.md).
:::
### Method 2: Using the EventBusService
If the notification provider you’re using isn’t configured to handle this event, or you want to implement some other custom logic, you can subscribe to the event using the `EventBusService`:
```ts title=src/subscribers/customer-confirmation.ts
import { Customer, EventBusService } from "@medusajs/medusa"
type InjectedDependencies = {
eventBusService: EventBusService
}
class CustomerConfirmationSubscriber {
constructor({ eventBusService }: InjectedDependencies) {
eventBusService.subscribe(
"customer.created",
this.handleCustomerConfirmation
)
}
handleCustomerConfirmation = async (data: Customer) => {
// TODO: handle event
}
}
export default CustomerConfirmationSubscriber
```
When using this method, you’ll have to handle the logic of sending the confirmation email to the customer inside the handler function, which in this case is `handleCustomerConfirmation`.
## Step 3: Handle the Event
The `handleCustomerConfirmation` method receives a `data` object as a parameter which is a payload emitted when the event was triggered. This object is the entire customer object. So, you can find in it fields like `first_name`, `last_name`, `email`, and more.
You also export a handler function `handleCustomerConfirmation`. In the parameter it receives, the `data` object is the payload emitted when the event was triggered, which is the entire customer object. So, you can find in it fields like `first_name`, `last_name`, `email`, and more.
In this method, you should typically send an email to the customer. You can place any content in the email, such as welcoming them to your store or thanking them for registering.
### Example: Using SendGrid
For example, you can implement this subscriber to send emails using SendGrid:
For example, you can implement this subscriber to send emails using [SendGrid](../../../plugins/notifications/sendgrid.mdx):
```ts title=src/subscribers/customer-confirmation.ts
import { Customer, EventBusService } from "@medusajs/medusa"
import {
type SubscriberConfig,
type SubscriberArgs,
CustomerService,
} from "@medusajs/medusa"
type InjectedDependencies = {
eventBusService: EventBusService,
sendgridService: any
export default async function handleCustomerCreated({
data, eventName, container, pluginOptions,
}: SubscriberArgs<Record<string, string>>) {
const sendGridService = container.resolve("sendgridService")
sendGridService.sendEmail({
templateId: "customer-confirmation",
from: "hello@medusajs.com",
to: data.email,
dynamic_template_data: {
// any data necessary for your template...
first_name: data.first_name,
last_name: data.last_name,
},
})
}
class CustomerConfirmationSubscriber {
protected sendGridService: any
constructor({
eventBusService,
sendgridService,
}: InjectedDependencies) {
this.sendGridService = sendgridService
eventBusService.subscribe(
"customer.created",
this.handleCustomerConfirmation
)
}
handleCustomerConfirmation = async (data: Customer) => {
this.sendGridService.sendEmail({
templateId: "customer-confirmation",
from: "hello@medusajs.com",
to: data.email,
dynamic_template_data: {
// any data necessary for your template...
first_name: data.first_name,
last_name: data.last_name,
},
})
}
export const config: SubscriberConfig = {
event: CustomerService.Events.CREATED,
context: {
subscriberId: "customer-created-handler",
},
}
export default CustomerConfirmationSubscriber
```
Notice that you should replace the values in the object passed to the `sendEmail` method:
@@ -188,3 +108,39 @@ Notice that you should replace the values in the object passed to the `sendEmail
- `from`: Should be the from email.
- `to`: Should be the customer’s email.
- `data`: Should be an object holding any data that should be passed to your SendGrid email template.
---
## Method 2: Using the NotificationService
If the notification provider you’re using already implements the logic to handle this event, you can create a [Loader](../../../development/loaders/overview.mdx) to subscribe the Notification provider to the `customer.created` event.
For example:
```ts title=src/loaders/customer-confirmation.ts
import {
MedusaContainer,
NotificationService,
} from "@medusajs/medusa"
export default async (
container: MedusaContainer
): Promise<void> => {
const notificationService = container.resolve<
NotificationService
>("notificationService")
notificationService.subscribe(
"customer.created",
"<NOTIFICATION_PROVIDER_IDENTIFIER>"
)
}
```
Where `<NOTIFICATION_PROVIDER_IDENTIFIER>` is the identifier for your notification provider. For example, `sendgrid`.
:::note
You can learn more about handling events with the Notification Service using [this documentation](../../../development/notification/create-notification-provider.md).
:::
www/apps/docs/content/modules/customers/storefront/implement-customer-profiles.mdx
+1 -1
View File
@@ -287,7 +287,7 @@ If the request has been processed successfully, it returns a `204` status code i
:::note
If the customer doesn’t receive an email after this request, make sure that you’ve set up a Notification provider like [SendGrid](../../../plugins/notifications/sendgrid.mdx) successfully. You also need to add a subscriber that handles the [customer.password_reset](../../../development/events/events-list.md#customer-events) event and sends the email.
If the customer doesn’t receive an email after this request, make sure that you’ve set up a Notification provider like [SendGrid](../../../plugins/notifications/sendgrid.mdx) successfully. You also need to add a [subscriber](../../../development/events/create-subscriber.md) that handles the [customer.password_reset](../../../development/events/events-list.md#customer-events) event and sends the email.
:::
www/apps/docs/content/modules/gift-cards/backend/send-gift-card-to-customer.md
+104 -101
View File
@@ -13,7 +13,7 @@ Once the customer purchases a gift card, they should receive the code of the gif
Typically, the code would be sent by email, however, you’re free to choose how you deliver the gift card code to the customer.
This document shows you how to track when a gift card has been purchased so that you can send its code to the customer.
This document shows you how to track when a gift card is purchased so that you can send its code to the customer.
:::tip
@@ -31,121 +31,124 @@ It's assumed that you already have a Medusa backend installed and set up. If not
### Notification Provider
To send an email or another type of notification method, you must have a notification provider installed or configured. You can either install an existing plugin or [create your own](../../../development/notification/create-notification-provider.md).
To send an email or another type of notification method, you must have a notification provider installed or configured. You can either install an [existing plugin](../../../plugins/notifications/index.mdx) or [create your own](../../../development/notification/create-notification-provider.md).
---
## Step 1: Create a Subscriber
## Methed 1: Using a Subscriber
To subscribe to and handle an event, you must create a subscriber.
:::info
You can learn more about subscribers in the [Subscribers](../../../development/events/subscribers.mdx) documentation.
:::
To subscribe to and handle an event, you must create a [subscriber](../../../development/events/subscribers.mdx).
Create the file `src/subscribers/gift-card.ts` with the following content:
```ts title=src/subscribers/gift-card.ts
type InjectedDependencies = {
// TODO add necessary dependencies
}
class GiftCardSubscriber {
constructor(container: InjectedDependencies) {
// TODO subscribe to event
}
}
export default GiftCardSubscriber
```
You’ll be adding in the next step the necessary dependencies to the subscriber.
:::info
You can learn more about [dependency injection](../../../development/fundamentals/dependency-injection.md) in this documentation.
:::
---
## Step 2: Subscribe to the Event
In this step, you’ll subscribe to the event `gift_card.created` to send the customer a notification about their gift card.
There are two ways to do this:
### Method 1: Using the NotificationService
If the notification provider you’re using already implements the logic to handle this event, you can subscribe to the event using the `NotificationService`:
```ts title=src/subscribers/gift-card.ts
import { NotificationService } from "@medusajs/medusa"
type InjectedDependencies = {
notificationService: NotificationService
}
class GiftCardSubscriber {
constructor({ notificationService }: InjectedDependencies) {
notificationService.subscribe(
"gift_card.created",
"<NOTIFICATION_PROVIDER_IDENTIFIER>"
)
}
}
export default GiftCardSubscriber
```
Where `<NOTIFICATION_PROVIDER_IDENTIFIER>` is the identifier for your notification provider. For example, if you’re using SendGrid, the identifier is `sendgrid`.
:::info
You can learn more about handling events with the Notification Service using [this documentation](../../../development/notification/create-notification-provider.md).
:::
### Method 2: Using the EventBusService
If the notification provider you’re using isn’t configured to handle this event, or you want to implement some other custom logic, you can subscribe to the event using the `EventBusService`:
```ts title=src/subscribers/gift-card.ts
import {
EventBusService,
type SubscriberConfig,
type SubscriberArgs,
GiftCardService,
} from "@medusajs/medusa"
type InjectedDependencies = {
eventBusService: EventBusService
giftCardService: GiftCardService
export default async function handleGiftCardCreated({
data, eventName, container, pluginOptions,
}: SubscriberArgs<Record<string, string>>) {
// TODO: handle event
}
class GiftCardSubscriber {
giftCardService: GiftCardService
constructor({
eventBusService,
giftCardService,
}: InjectedDependencies) {
this.giftCardService = giftCardService
eventBusService.subscribe(
"gift_card.created", this.handleGiftCard)
}
handleGiftCard = async (data) => {
const giftCard = await this.giftCardService.retrieve(
data.id
)
// TODO send customer the gift card code
}
export const config: SubscriberConfig = {
event: GiftCardService.Events.CREATED,
context: {
subscriberId: "gift-card-created-handler",
},
}
export default GiftCardSubscriber
```
When using this method, you’ll have to handle the logic of sending the code to the customer inside the handler function, which in this case is `handleGiftCard`.
In this file, you export a configuration object indicating that the subscriber is listening to the `GiftCardService.Events.CREATED` (or `gift_card.created`) event.
The `handleGiftCard` event receives a `data` object as a parameter. This object holds the `id` property which is the ID of the gift card. You can retrieve the full gift card object using the [GiftCardService](../../../references/services/classes/GiftCardService.mdx)
You also export a handler function `handleGiftCardCreated`. In the parameter it receives, the `data` object is the payload emitted when the event was triggered, which is an object containing the ID of the gift card in the `id` property.
In this method, you should typically send an email to the customer. You can place any content in the email, such as the code of the gift card.
### Example: Using SendGrid
For example, you can implement this subscriber to send emails using [SendGrid](../../../plugins/notifications/sendgrid.mdx):
```ts title=src/subscribers/gift-card.ts
import {
type SubscriberConfig,
type SubscriberArgs,
GiftCardService,
} from "@medusajs/medusa"
export default async function handleGiftCardCreated({
data, eventName, container, pluginOptions,
}: SubscriberArgs<Record<string, string>>) {
const sendGridService = container.resolve("sendgridService")
const giftCardService: GiftCardService = container.resolve(
"giftCardService"
)
const giftCard = await giftCardService.retrieve(data.id, {
relations: ["order"],
})
sendGridService.sendEmail({
templateId: "gift-card-created",
from: "hello@medusajs.com",
to: giftCard.order.email,
dynamic_template_data: {
// any data necessary for your template...
code: giftCard.code,
},
})
}
export const config: SubscriberConfig = {
event: GiftCardService.Events.CREATED,
context: {
subscriberId: "gift-card-created-handler",
},
}
```
Notice that you should replace the values in the object passed to the `sendEmail` method:
- `templateId`: Should be the ID of your confirmation email template in SendGrid.
- `from`: Should be the from email.
- `to`: Should be the customer’s email.
- `data`: Should be an object holding any data that should be passed to your SendGrid email template.
---
## Method 2: Using the NotificationService
If the notification provider you’re using already implements the logic to handle this event, you can create a [Loader](../../../development/loaders/overview.mdx) to subscribe the Notification provider to the `gift_card.created` event.
For example:
```ts title=src/loaders/gift-card-event.ts
import {
MedusaContainer,
NotificationService,
} from "@medusajs/medusa"
export default async (
container: MedusaContainer
): Promise<void> => {
const notificationService = container.resolve<
NotificationService
>("notificationService")
notificationService.subscribe(
"gift_card.created",
"<NOTIFICATION_PROVIDER_IDENTIFIER>"
)
}
```
Where `<NOTIFICATION_PROVIDER_IDENTIFIER>` is the identifier for your notification provider. For example, `sendgrid`.
:::note
You can learn more about handling events with the Notification Service using [this documentation](../../../development/notification/create-notification-provider.md).
:::
www/apps/docs/content/modules/orders/backend/handle-order-claim-event.md
+95 -135
View File
@@ -9,14 +9,12 @@ In this document, you’ll learn how to handle the order claim event and send a
## Overview
When a guest customer places an order, the order is not associated with a customer. It is associated with an email address.
When a guest customer places an order, the order isn't associated with a customer. It's associated with an email address.
After the customer registers, later on, they can claim that order by providing the order’s ID.
When the customer requests to claim the order, the event `order-update-token.created` is triggered on the Medusa backend. This event should be used to send the customer a confirmation email.
### What You’ll Learn
In this document, you’ll learn how to handle the `order-update-token.created` event on the backend to send the customer a confirmation email.
---
@@ -35,170 +33,132 @@ This document has an example using the [SendGrid](../../../plugins/notifications
---
## Step 1: Create a Subscriber
## Method 1: Using a Subscriber
To subscribe to and handle an event, you must create a subscriber.
To subscribe to an event, you must create a subscriber.
:::tip
:::note
You can learn more about subscribers in the [Subscribers](../../../development/events/subscribers.mdx) documentation.
You can learn more about subscribers in the [Subscribers documentation](../../../development/events/subscribers.mdx).
:::
Create the file `src/subscribers/claim-order.ts` with the following content:
Create the file `src/subscribers/order-claim.ts` with the following content:
```ts title=src/subscribers/claim-order.ts
type InjectedDependencies = {
// TODO add necessary dependencies
```ts title=src/subscribers/order-claim.ts
import {
type SubscriberConfig,
type SubscriberArgs,
} from "@medusajs/medusa"
export default async function handleOrderClaim({
data, eventName, container, pluginOptions,
}: SubscriberArgs<Record<string, string>>) {
// TODO: handle event
}
class ClaimOrderSubscriber {
constructor(container: InjectedDependencies) {
// TODO subscribe to event
}
export const config: SubscriberConfig = {
event: "order-update-token.created",
context: {
subscriberId: "customer-created-handler",
},
}
export default ClaimOrderSubscriber
```
You’ll be adding in the next step the necessary dependencies to the subscriber.
In this file, you export a configuration object indicating that the subscriber is listening to the `order-update-token.created` event.
:::info
You also export a handler function `handleOrderClaim`. In the parameter it receives, the `data` object is the payload emitted when the event was triggered, which is an object of the following format:
You can learn more about [dependency injection](../../../development/fundamentals/dependency-injection.md) in this documentation.
:::
---
## Step 2: Subscribe to the Event
In this step, you’ll subscribe to the `order-update-token.created` event to send the customer a notification about their order edit.
There are two ways to do this:
### Method 1: Using the NotificationService
If the notification provider you’re using already implements the logic to handle this event, you can subscribe to the event using the `NotificationService`:
```ts title=src/subscribers/claim-order.ts
import { NotificationService } from "@medusajs/medusa"
type InjectedDependencies = {
notificationService: NotificationService
```ts
data = {
// string - email of order
old_email,
// string - ID of customer
new_customer_id,
// array of string - IDs of orders
orders,
// string - token used for verification
token,
}
class ClaimOrderSubscriber {
constructor({ notificationService }: InjectedDependencies) {
notificationService.subscribe(
"order-update-token.created",
"<NOTIFICATION_PROVIDER_IDENTIFIER>"
)
}
}
export default ClaimOrderSubscriber
```
Where `<NOTIFICATION_PROVIDER_IDENTIFIER>` is the identifier for your notification provider.
In this method, you should typically send an email to the customer. You can place any content in the email, but should mainly include the link to confirm claiming the order.
:::info
You can learn more about handling events with the Notification Service using [this documentation](../../../development/notification/create-notification-provider.md).
:::
### Method 2: Using the EventBusService
If the notification provider you’re using isn’t configured to handle this event, or you want to implement some other custom logic, you can subscribe to the event using the `EventBusService`:
```ts title=src/subscribers/claim-order.ts
import { EventBusService } from "@medusajs/medusa"
type InjectedDependencies = {
eventBusService: EventBusService
}
class ClaimOrderSubscriber {
constructor({ eventBusService }: InjectedDependencies) {
eventBusService.subscribe(
"order-update-token.created",
this.handleRequestClaimOrder
)
}
handleRequestClaimOrder = async (data) => {
// TODO: handle event
}
}
export default ClaimOrderSubscriber
```
When using this method, you’ll have to handle the logic of sending the confirmation email to the customer inside the handler function, which in this case is `handleRequestClaimOrder`.
The `handleRequestClaimOrder` event receives a `data` object as a parameter. This object holds the following properties:
1. `old_email`: The email associated with the orders.
2. `new_customer_id`: The ID of the customer claiming the orders.
3. `orders`: An array of the order IDs that the customer is requesting to claim.
4. `token`: A verification token. This token is used to later verify the claim request and associate the order with the customer.
In this method, you should typically send an email to the customer’s old email. In the email, you should link to a page in your storefront and pass the `token` as a parameter.
The page would then send a request to the backend to verify that the `token` is valid and associate the order with the customer. You can read more about how to implement this in your storefront in [this documentation](../storefront/implement-claim-order.mdx).
---
## Example: Using SendGrid
### Example: Using SendGrid
For example, you can implement this subscriber to send emails using SendGrid:
<!-- eslint-disable max-len -->
```ts title=src/subscribers/order-claim.ts
import {
type SubscriberConfig,
type SubscriberArgs,
} from "@medusajs/medusa"
```ts title=src/subscribers/claim-order.ts
import { EventBusService } from "@medusajs/medusa"
export default async function handleOrderClaim({
data, eventName, container, pluginOptions,
}: SubscriberArgs<Record<string, string>>) {
const sendGridService = container.resolve("sendgridService")
type InjectedDependencies = {
eventBusService: EventBusService,
sendgridService: any
sendGridService.sendEmail({
templateId: "order-claim-confirmation",
from: "hello@medusajs.com",
to: data.old_email,
dynamic_template_data: {
link:
`http://example.com/confirm-order-claim/${data.token}`,
// other data...
},
})
}
class ClaimOrderSubscriber {
protected sendGridService: any
constructor({
eventBusService,
sendgridService,
}: InjectedDependencies) {
this.sendGridService = sendgridService
eventBusService.subscribe(
"order-update-token.created",
this.handleRequestClaimOrder
)
}
handleRequestClaimOrder = async (data) => {
this.sendGridService.sendEmail({
templateId: "order-claim-confirmation",
from: "hello@medusajs.com",
to: data.old_email,
dynamic_template_data: {
link: `http://example.com/confirm-order-claim/${data.token}`,
// other data...
},
})
}
export const config: SubscriberConfig = {
event: "order-update-token.created",
context: {
subscriberId: "customer-created-handler",
},
}
export default ClaimOrderSubscriber
```
Notice how the `token` is passed to the storefront link as a parameter.
---
## Method 2: Using the NotificationService
If the notification provider you’re using already implements the logic to handle this event, you can create a [Loader](../../../development/loaders/overview.mdx) to subscribe the Notification provider to the `order-update-token.created` event.
For example:
```ts title=src/loaders/order-claim.ts
import {
MedusaContainer,
NotificationService,
} from "@medusajs/medusa"
export default async (
container: MedusaContainer
): Promise<void> => {
const notificationService = container.resolve<
NotificationService
>("notificationService")
notificationService.subscribe(
"order-update-token.created",
"<NOTIFICATION_PROVIDER_IDENTIFIER>"
)
}
```
Where `<NOTIFICATION_PROVIDER_IDENTIFIER>` is the identifier for your notification provider. For example, `sendgrid`.
:::note
You can learn more about handling events with the Notification Service using [this documentation](../../../development/notification/create-notification-provider.md).
:::
---
## See Also
- [Implement claim-order flow in your storefront](../storefront/implement-claim-order.mdx)
www/apps/docs/content/modules/orders/backend/send-order-confirmation.md
+95 -198
View File
@@ -11,22 +11,12 @@ In this document, you’ll learn how to send an order confirmation email to the
When an order is placed, the `order.placed` event is triggered. You can listen to this event in a subscriber to perform an action, such as send the customer an order confirmation email.
This guide explains how to create the subscriber and how to use SendGrid to send the confirmation email. SendGrid is only used to illustrate how the process works, but you’re free to use any other notification service.
:::note
SendGrid is already configured to send emails when an order has been placed. So, by installing and configuring the plugin, you don't need to actually handle sending the order confirmation email. It's used as an example here to illustrate the process only.
:::
This guide explains how you can listen to the `order.placed` event to send an email to the customer.
---
## Prerequisites
### Medusa Backend
It’s assumed you already have the Medusa backend installed. If not, you can either use the [create-medusa-app command](../../../create-medusa-app.mdx) to install different Medusa tools, including the backend, or [install the backend only](../../../development/backend/install.mdx).
### Event Bus Module
The event bus module trigger the event to the listening subscribers. So, it’s required to have an event bus module installed and configured on your Medusa backend.
@@ -41,221 +31,128 @@ You can also find other available Notification provider plugins in the [Plugins
---
## Step 1: Create the Subscriber
## Method 1: Using a Subscriber
To subscribe to and handle an event, you must create a subscriber.
To subscribe to an event, you must create a [subscriber](../../../development/events/subscribers.mdx).
:::note
Create the file `src/subscribers/order-placed.ts` with the following content:
You can learn more about subscribers in the [Subscribers documentation](../../../development/events/subscribers.mdx).
```ts title=src/subscribers/order-placed.ts
import {
type SubscriberConfig,
type SubscriberArgs,
OrderService,
} from "@medusajs/medusa"
:::
Create the file `src/subscribers/order-confirmation.ts` with the following content:
```ts title=src/subscribers/order-confirmation.ts
type InjectedDependencies = {
// TODO add necessary dependencies
export default async function handleOrderPlaced({
data, eventName, container, pluginOptions,
}: SubscriberArgs<Record<string, string>>) {
// TODO: handle event
}
class OrderConfirmationSubscriber {
constructor(container: InjectedDependencies) {
// TODO subscribe to event
}
export const config: SubscriberConfig = {
event: OrderService.Events.PLACED,
context: {
subscriberId: "order-placed-handler",
},
}
export default OrderConfirmationSubscriber
```
You’ll be adding in the next step the necessary dependencies to the subscriber.
In this file, you export a configuration object indicating that the subscriber is listening to the `OrderService.Events.PLACED` (or `order.placed`) event.
You also export a handler function `handleCustomerConfirmation`. In the parameter it receives, the `data` object is the payload emitted when the event was triggered, which is an object that includes the ID of the order in the `id` property.
In this method, you should typically send an email to the customer. You can place any content in the email, such as the order's items and total.
### Example: Using SendGrid
:::note
You can learn more about dependency injection in [this documentation](../../../development/fundamentals/dependency-injection.md).
This example is only used to illustrate how the functionality can be implemented. The SendGrid plugin automatically handles sending an email when an order is placed once you install and configure the plugin in your backend.
:::
For example, you can implement this subscriber to send emails using [SendGrid](../../../plugins/notifications/sendgrid.mdx):
```ts title=src/subscribers/order-placed.ts
import {
type SubscriberConfig,
type SubscriberArgs,
OrderService,
} from "@medusajs/medusa"
export default async function handleOrderPlaced({
data, eventName, container, pluginOptions,
}: SubscriberArgs<Record<string, string>>) {
const sendGridService = container.resolve("sendgridService")
const orderService: OrderService = container.resolve(
"orderService"
)
const order = await orderService.retrieve(data.id, {
// you can include other relations as well
relations: ["items"],
})
sendGridService.sendEmail({
templateId: "order-confirmation",
from: "hello@medusajs.com",
to: order.email,
dynamic_template_data: {
// any data necessary for your template...
items: order.items,
status: order.status,
},
})
}
export const config: SubscriberConfig = {
event: OrderService.Events.PLACED,
context: {
subscriberId: "order-placed-handler",
},
}
```
Notice that you should replace the values in the object passed to the `sendEmail` method:
- `templateId`: Should be the ID of your confirmation email template in SendGrid.
- `from`: Should be the from email.
- `to`: Should be the customer’s email.
- `data`: Should be an object holding any data that should be passed to your SendGrid email template.
---
## Step 2: Subscribe to the Event
## Method 2: Using the NotificationService
In this step, you’ll subscribe to the `order.placed` event to send the customer an order confirmation email.
If the notification provider you’re using already implements the logic to handle this event, you can create a [Loader](../../../development/loaders/overview.mdx) to subscribe the Notification provider to the `order.placed` event.
There are two ways to do this:
For example:
### Method 1: Using the NotificationService
```ts title=src/loaders/customer-confirmation.ts
import {
MedusaContainer,
NotificationService,
} from "@medusajs/medusa"
If the notification provider you’re using already implements the logic to handle this event, you can subscribe to the event using the `NotificationService`:
export default async (
container: MedusaContainer
): Promise<void> => {
const notificationService = container.resolve<
NotificationService
>("notificationService")
```ts title=src/subscribers/order-confirmation.ts
import { NotificationService } from "@medusajs/medusa"
type InjectedDependencies = {
notificationService: NotificationService
notificationService.subscribe(
"order.placed",
"<NOTIFICATION_PROVIDER_IDENTIFIER>"
)
}
class OrderConfirmationSubscriber {
constructor({ notificationService }: InjectedDependencies) {
notificationService.subscribe(
"order.placed",
"<NOTIFICATION_PROVIDER_IDENTIFIER>"
)
}
}
export default OrderConfirmationSubscriber
```
Where `<NOTIFICATION_PROVIDER_IDENTIFIER>` is the identifier for your notification provider.
Where `<NOTIFICATION_PROVIDER_IDENTIFIER>` is the identifier for your notification provider. For example, `sendgrid`.
:::note
You can learn more about handling events with the Notification Service using [this documentation](../../../development/notification/create-notification-provider.md).
:::
### Method 2: Using the EventBusService
If the notification provider you’re using isn’t configured to handle this event, or you want to implement some other custom logic, you can subscribe to the event using the `EventBusService`:
```ts title=src/subscribers/order-confirmation.ts
import { EventBusService } from "@medusajs/medusa"
type InjectedDependencies = {
eventBusService: EventBusService
}
class OrderConfirmationSubscriber {
constructor({ eventBusService }: InjectedDependencies) {
eventBusService.subscribe(
"order.placed",
this.handleOrderConfirmation
)
}
handleOrderConfirmation = async (
data: Record<string, any>
) => {
// TODO: handle event
}
}
export default OrderConfirmationSubscriber
```
When using this method, you’ll have to handle the logic of sending the order confirmation email to the customer inside the handler function, which in this case is `handleOrderConfirmation`.
## Step 3: Handle the Event
The `handleOrderConfirmation` event receives a `data` object as a parameter. This object holds two properties:
- `id`: the ID of the order that was placed.
- `no_notification`: a boolean value indicating whether the customer should receive notifications about the order or not.
In this method, you should typically send an email to the customer if `no_notification` is enabled.
To retrieve the order's details, you can add the `OrderService` into `InjectedDependencies` and use it within `handleOrderConfirmation`. For example:
```ts title=src/subscribers/order-confirmation.ts
import { EventBusService, OrderService } from "@medusajs/medusa"
type InjectedDependencies = {
eventBusService: EventBusService
orderService: OrderService
}
class OrderConfirmationSubscriber {
protected readonly orderService_: OrderService
constructor({
eventBusService,
orderService,
}: InjectedDependencies) {
this.orderService_ = orderService
eventBusService.subscribe(
"order.placed",
this.handleOrderConfirmation
)
}
handleOrderConfirmation = async (
data: Record<string, any>
) => {
const order = await this.orderService_.retrieve(data.id, {
// you can include other relations as well
relations: ["items"],
})
// TODO: handle event
}
}
export default OrderConfirmationSubscriber
```
After retrieving the order, you can add the logic necessary to send the email. In the email, you can include any content you want. For example, you can show the order's items or the order's status.
### Example: Using SendGrid
:::note
This example is only used to illustrate how the functionality can be implemented. As mentioned in the introduction, there's actually no need to implement this subscriber if you have the SendGrid plugin installed and configured, as it will automatically handle it.
:::
For example, you can implement this subscriber to send emails using SendGrid:
```ts title=src/subscribers/order-confirmation.ts
import { EventBusService, OrderService } from "@medusajs/medusa"
type InjectedDependencies = {
eventBusService: EventBusService
orderService: OrderService
sendgridService: any
}
class OrderConfirmationSubscriber {
protected readonly orderService_: OrderService
protected readonly sendgridService_: any
constructor({
eventBusService,
orderService,
sendgridService,
}: InjectedDependencies) {
this.orderService_ = orderService
this.sendgridService_ = sendgridService
eventBusService.subscribe(
"order.placed",
this.handleOrderConfirmation
)
}
handleOrderConfirmation = async (
data: Record<string, any>
) => {
const order = await this.orderService_.retrieve(data.id, {
// you can include other relations as well
relations: ["items"],
})
this.sendgridService_.sendEmail({
templateId: "order-confirmation",
from: "hello@medusajs.com",
to: order.email,
dynamic_template_data: {
// any data necessary for your template...
items: order.items,
status: order.status,
},
})
}
}
export default OrderConfirmationSubscriber
```
Notice that you should replace the values in the object passed to the `sendEmail` method:
- `templateId`: Should be the ID of your order confirmation email template in SendGrid.
- `from`: Should be the from email.
- `to`: Should be the email associated with the order.
- `data`: Should be an object holding any data that should be passed to your SendGrid email template.
www/apps/docs/content/modules/users/backend/send-invite.md
+87 -130
View File
@@ -31,160 +31,81 @@ You can also find other available Notification provider plugins in the [Plugins
---
## Step 1: Create the Subscriber
## Method 1: Using a Subscriber
To subscribe to and handle an event, you must create a subscriber.
To subscribe to an event, you must create a [subscriber](../../../development/events/subscribers.mdx).
:::tip
Create the file `src/subscribers/invite-created.ts` with the following content:
You can learn more about subscribers in the [Subscribers documentation](../../../development/events/subscribers.mdx).
```ts title=src/subscribers/invite-created.ts
import {
type SubscriberConfig,
type SubscriberArgs,
} from "@medusajs/medusa"
:::
Create the file `src/subscribers/invite.ts` with the following content:
```ts title=src/subscribers/invite.ts
type InjectedDependencies = {
// TODO add necessary dependencies
export default async function handleInviteCreated({
data, eventName, container, pluginOptions,
}: SubscriberArgs<Record<string, string>>) {
// TODO: handle event
}
class InviteSubscriber {
constructor(container: InjectedDependencies) {
// TODO subscribe to event
}
export const config: SubscriberConfig = {
event: "invite.created",
context: {
subscriberId: "invite-created-handler",
},
}
export default InviteSubscriber
```
You’ll be adding in the next step the necessary dependencies to the subscriber.
In this file, you export a configuration object indicating that the subscriber is listening to the `invite.created` event.
:::tip
You also export a handler function `handleInviteCreated`. In the parameter it receives, the `data` object is the payload emitted when the event was triggered, which is an object of the following format:
You can learn more about dependency injection in [this documentation](../../../development/fundamentals/dependency-injection.md).
:::
---
## Step 2: Subscribe to the Event
In this step, you’ll subscribe to the `invite.created` event to send the user the invitation email.
There are two ways to do this:
### Method 1: Using the NotificationService
If the notification provider you’re using already implements the logic to handle this event, you can subscribe to the event using the `NotificationService`:
```ts title=src/subscribers/invite.ts
import { NotificationService } from "@medusajs/medusa"
type InjectedDependencies = {
notificationService: NotificationService
```ts
{
// string - ID of invite
id
// string - token generated to validate the invited user
token,
// string - email of invited user
user_email
}
class InviteSubscriber {
constructor({ notificationService }: InjectedDependencies) {
notificationService.subscribe(
"invite.created",
"<NOTIFICATION_PROVIDER_IDENTIFIER>"
)
}
}
export default InviteSubscriber
```
Where `<NOTIFICATION_PROVIDER_IDENTIFIER>` is the identifier for your notification provider.
:::tip
You can learn more about handling events with the Notification Service using [this documentation](../../../development/notification/create-notification-provider.md).
:::
### Method 2: Using the EventBusService
If the notification provider you’re using isn’t configured to handle this event, or you want to implement some other custom logic, you can subscribe to the event using the `EventBusService`:
```ts title=src/subscribers/invite.ts
import { EventBusService } from "@medusajs/medusa"
type InjectedDependencies = {
eventBusService: EventBusService
}
class InviteSubscriber {
constructor({ eventBusService }: InjectedDependencies) {
eventBusService.subscribe(
"invite.created",
this.handleInvite
)
}
handleInvite = async (data: Record<string, any>) => {
// TODO: handle event
}
}
export default InviteSubscriber
```
When using this method, you’ll have to handle the logic of sending the invitation email inside the handler function, which in this case is `handleInvite`.
---
## Step 3: Handle the Event
The `handleInvite` method receives a `data` object as a parameter which is a payload emitted when the event was triggered. This object has the following properties:
- `id`: a string indicating the ID of the invite.
- `token`: a string indicating the token of the invite. This token is useful to pass along to a frontend link that can be used to accept the invite.
- `user_email`: a string indicating the email of the invited user.
In this method, you should typically send an email to the invited user. You can place any content in the email, but typically you would include a link to your frontend that allows the invited user to enter their details and accept the invite.
In this method, you should typically send an email to the user. You can place any content in the email, but should mainly include the invite token.
### Example: Using SendGrid
For example, you can implement this subscriber to send emails using SendGrid:
```ts title=src/subscribers/invite.ts
import { EventBusService } from "@medusajs/medusa"
import {
type SubscriberConfig,
type SubscriberArgs,
} from "@medusajs/medusa"
type InjectedDependencies = {
eventBusService: EventBusService
sendgridService: any
export default async function handleInviteCreated({
data, eventName, container, pluginOptions,
}: SubscriberArgs<Record<string, string>>) {
const sendGridService = container.resolve("sendgridService")
sendGridService.sendEmail({
templateId: "send-invite",
from: "hello@medusajs.com",
to: data.user_email,
dynamic_template_data: {
// any data necessary for your template...
token: data.token,
},
})
}
class InviteSubscriber {
protected sendGridService: any
constructor({
eventBusService,
sendgridService,
}: InjectedDependencies) {
this.sendGridService = sendgridService
eventBusService.subscribe(
"invite.created",
this.handleInvite
)
}
handleInvite = async (data: Record<string, any>) => {
this.sendGridService.sendEmail({
templateId: "send-invite",
from: "hello@medusajs.com",
to: data.user_email,
dynamic_template_data: {
// any data necessary for your template...
token: data.token,
},
})
}
export const config: SubscriberConfig = {
event: "invite.created",
context: {
subscriberId: "invite-created-handler",
},
}
export default InviteSubscriber
```
Notice that you should replace the values in the object passed to the `sendEmail` method:
@@ -193,3 +114,39 @@ Notice that you should replace the values in the object passed to the `sendEmai
- `from`: Should be the from email.
- `to`: Should be the invited user’s email.
- `data`: Should be an object holding any data that should be passed to your SendGrid email template. In the example above, you pass the token, which you can use in the SendGrid template to format the frontend link (for example, `<FRONTEND_LINK>/invite?token={{token}}`, where `<FRONTEND_LINK>` is your frontend’s hostname.)
---
## Method 2: Using the NotificationService
If the notification provider you’re using already implements the logic to handle this event, you can create a [Loader](../../../development/loaders/overview.mdx) to subscribe the Notification provider to the `invite.created` event.
For example:
```ts title=src/loaders/customer-confirmation.ts
import {
MedusaContainer,
NotificationService,
} from "@medusajs/medusa"
export default async (
container: MedusaContainer
): Promise<void> => {
const notificationService = container.resolve<
NotificationService
>("notificationService")
notificationService.subscribe(
"invite.created",
"<NOTIFICATION_PROVIDER_IDENTIFIER>"
)
}
```
Where `<NOTIFICATION_PROVIDER_IDENTIFIER>` is the identifier for your notification provider. For example, `sendgrid`.
:::note
You can learn more about handling events with the Notification Service using [this documentation](../../../development/notification/create-notification-provider.md).
:::