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
2024-05-22 13:37:48 +03:00
parent ff5d573887
commit 154673f3d8
55 changed files with 1674 additions and 3791 deletions
@@ -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.