docs: added send invitation guide (medusajs#3994)

* docs: added send invitation guide * eslint fixes
Sosyetekadir · May 3, 2023 · f8532cb · f8532cb
1 parent d44737c
commit f8532cb
Show file tree

Hide file tree

Showing 5 changed files with 205 additions and 12 deletions.
diff --git a/docs/content/modules/customers/backend/send-confirmation.md b/docs/content/modules/customers/backend/send-confirmation.md
@@ -17,10 +17,6 @@ This guide will explain how to create the subscriber and how to use SendGrid to
 
 ## 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.
@@ -139,7 +135,7 @@ When using this method, you’ll have to handle the logic of sending the confirm
 
 ## Step 3: Handle the Event
 
-The `handleCustomerConfirmation` event receives a `data` object as a parameter. This object is the entire customer object. So, you can find in it fields like `first_name`, `last_name`, `email`, and more.
+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.
 
 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.
 

diff --git a/docs/content/modules/users/backend/send-invite.md b/docs/content/modules/users/backend/send-invite.md
@@ -0,0 +1,195 @@
+---
+description: "Users are admins that can manage the ecommerce store’s data and operations. Learn about the available features and guides."
+addHowToData: true
+---
+
+# How to Send an Invitation Email
+
+In this document, you’ll learn how to send an invitation email to an invited user.
+
+## Overview
+
+Users can be invited to join a store by other users. When a new invite is created, the `invite.created` event is triggered. This event is also triggered when an invite is resent.
+
+This guide explains how to subscribe to that event and send an email to the new user with the invitation link. The guide uses SendGrid as an example of illustration, but you can use any other notification service.
+
+---
+
+## Prerequisites
+
+### 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.
+
+The [Local Event Bus module](../../../development/events/modules/local.md) works in a development environment. For production, it’s recommended to use the [Redis Event Bus module](../../../development/events/modules/redis.md).
+
+### Notification Provider
+
+As mentioned in the overview, this guide illustrates how to send the email using SendGrid. If you intend to follow along, you must have the [SendGrid plugin](../../../plugins/notifications/sendgrid.mdx) installed and configured.
+
+You can also find other available Notification provider plugins in the [Plugins directory](https://medusajs.com/plugins/), or [create your own](../../../development/notification/create-notification-provider.md).
+
+---
+
+## Step 1: Create the Subscriber
+
+To subscribe to and handle an event, you must create a subscriber.
+
+:::tip
+
+You can learn more about subscribers in the [Subscribers documentation](../../../development/events/subscribers.mdx).
+
+:::
+
+Create the file `src/subscribers/invite.ts` with the following content:
+
+```ts title=src/subscribers/invite.ts
+type InjectedDependencies = {
+  // TODO add necessary dependencies
+}
+
+class InviteSubscriber {
+  constructor(container: InjectedDependencies) {
+    // TODO subscribe to event
+  }
+}
+
+export default InviteSubscriber
+```
+
+You’ll be adding in the next step the necessary dependencies to the subscriber.
+
+:::tip
+
+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
+}
+
+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.
+
+### 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"
+
+type InjectedDependencies = {
+  eventBusService: EventBusService
+  sendgridService: any
+}
+
+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,
+      data: {
+        // any data necessary for your template...
+        token: data.token,
+      },
+    })
+  }
+}
+
+export default InviteSubscriber
+```
+
+Notice that you should replace the values in the object passed to the `sendEmail` method:
+
+- `templateId`: Should be the ID of your invitation email template in SendGrid.
+- `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.)
diff --git a/docs/content/modules/users/overview.mdx b/docs/content/modules/users/overview.mdx
@@ -95,12 +95,11 @@ Admins can invite users to join their team. Invites can be resent, accepted, or
   },
   {
     type: 'link',
-    href: '#',
+    href: '/modules/users/backend/send-invite',
     label: 'Backend: Send Invite',
     customProps: {
       icon: Icons['users-solid'],
       description: 'Learn how to send invites in the backend.',
-      isSoon: true
     }
   },
 ]} />

diff --git a/docs/content/modules/users/users.md b/docs/content/modules/users/users.md
@@ -66,3 +66,9 @@ The invitation process typically follows these steps in the Medusa backend:
 3. When the new user accepts the invite, the invitation is validated first to ensure it’s not expired. If it’s not expired, a new user is created using the `UserService`'s [create method](../../references/services/classes/UserService.md#create).
 
 If an invitation is expired, an existing user can resend the invite either using the Resend Invite endpoint or using the `InviteService`'s resend method. This would generate a new token and reset the expiry date.
+
+---
+
+## See Also
+
+- [How to send an invitation email](./backend/send-invite.md)
diff --git a/www/docs/sidebars.js b/www/docs/sidebars.js
@@ -1185,12 +1185,9 @@ module.exports = {
           },
         },
         {
-          type: "link",
-          href: "#",
+          type: "doc",
+          id: "modules/users/backend/send-invite",
           label: "Backend: Send Invite",
-          customProps: {
-            sidebar_is_soon: true,
-          },
         },
         {
           type: "link",