feat(notification-sendgrid): include ability to handle attachments (#8729)

* feat(notification-sendgrid): include ability to handle attachments array if passed to dynamicTemplateData.attachments

* docs: update sendgrid page.mdx

include attachments documentation in example

* ability to set from email, must be verified sender

* docs: update to include optional from property

* first-class optional vars for from & attachments

* docs: update for optional first-class vars

* Update www/apps/resources/app/architectural-modules/notification/sendgrid/page.mdx

Co-authored-by: Shahed Nasser <shahednasser@gmail.com>

---------

Co-authored-by: Stevche Radevski <sradevski@live.com>
Co-authored-by: Shahed Nasser <shahednasser@gmail.com>

packages/core/types/src/notification/common.ts

@@ -1,6 +1,34 @@
 import { BaseFilterable } from "../dal"
 import { OperatorMap } from "../dal/utils"
 
+/**
+ * @interface
+ *
+ * The structure for attachments in a notification.
+ */
+export interface Attachment {
+  /**
+   * The content of the attachment, encoded as a base64 string.
+   */
+  content: string
+  /**
+   * The filename of the attachment.
+   */
+  filename: string
+  /**
+   * The MIME type of the attachment.
+   */
+  content_type?: string
+  /**
+   * The disposition of the attachment, e.g., "inline" or "attachment".
+   */
+  disposition?: string
+  /**
+   * The ID, if the attachment is meant to be referenced within the body of the message.
+   */
+  id?: string
+}
+
 /**
  * @interface
  *
@@ -15,6 +43,14 @@ export interface NotificationDTO {
    * The recipient of the notification. It can be email, phone number, or username, depending on the channel.
    */
   to: string
+  /**
+   * The sender of the notification. It can be email, phone number, or username, depending on the channel.
+   */
+  from?: string | null
+  /**
+   * Optional attachments for the notification.
+   */
+  attachments?: Attachment[] | null
   /**
    * The channel through which the notification is sent, such as 'email' or 'sms'
    */

packages/core/types/src/notification/provider.ts

@@ -1,3 +1,5 @@
+import { Attachment } from "./common"
+
 /**
  * @interface
  *
@@ -8,6 +10,14 @@ export type ProviderSendNotificationDTO = {
    * The recipient of the notification. It can be email, phone number, or username, depending on the channel.
    */
   to: string
+  /**
+   * The sender of the notification. It can be email, phone number, or username, depending on the channel.
+   */
+  from?: string | null
+  /**
+   * Optional attachments for the notification.
+   */
+  attachments?: Attachment[] | null
   /**
    * The channel through which the notification is sent, such as 'email' or 'sms'
    */

packages/modules/providers/notification-sendgrid/src/services/sendgrid.ts

@@ -46,13 +46,26 @@ export class SendgridNotificationService extends AbstractNotificationProviderSer
       )
     }
 
-    const message = {
+    const attachments = Array.isArray(notification.attachments)
+      ? notification.attachments.map((attachment) => ({
+          content: attachment.content, // Base64 encoded string of the file
+          filename: attachment.filename,
+          content_type: attachment.content_type, // MIME type (e.g., 'application/pdf')
+          disposition: attachment.disposition ?? "attachment", // Default to 'attachment'
+          id: attachment.id ?? undefined, // Optional: unique identifier for inline attachments
+        }))
+      : undefined
+
+    const from = notification.from?.trim() || this.config_.from
+
+    const message: sendgrid.MailDataRequired = {
       to: notification.to,
-      from: this.config_.from,
+      from: from,
       templateId: notification.template,
       dynamicTemplateData: notification.data as
         | { [key: string]: any }
         | undefined,
+      attachments: attachments,
     }
 
     try {

www/apps/resources/app/architectural-modules/notification/sendgrid/page.mdx

@@ -12,20 +12,22 @@ The SendGrid Notification Module Provider integrates [SendGrid](https://sendgrid
 
 ## Install 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"
-  }
-]} />
+<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",
+    },
+  ]}
+/>
 
 To install the SendGrid Notification Module Provider, run the following command in the directory of your Medusa application:
 
@@ -154,9 +156,19 @@ export default async function productCreateHandler({
 
   await notificationModuleService.createNotifications({
     to: "test@gmail.com",
+    from: "test@medusajs.com", // Optional var, verified sender required
     channel: "email",
     template: "product-created",
     data,
+    attachments: [ // optional var
+      {
+        content: base64,
+        content_type: MIME type,
+        filename: filename.ext,
+        disposition: "attachment or inline attachment",
+        id: "id", // only needed for inline attachment
+      },
+    ]
   })
 }
 
@@ -172,6 +184,8 @@ In this subscriber:
 - By specifying the `email` channel, the SendGrid Notification Module Provider 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.
+- The `attachments` optional property allows you to pass attachments to the template in SendGrid.
+- The `from` optional property allows you to pass a single sender-verified email. If not provided, the value of the `from` configuration of the module is used.
 
 Then, start the Medusa application: