@medusajs/notification-sendgrid 2.22.0-snapshot-20261020204851 → 2.22.0

package/AGENTS.md

@@ -0,0 +1,54 @@
+# @medusajs/notification-sendgrid
+
+Notification Module provider that sends emails through SendGrid (`@sendgrid/mail`), using either SendGrid dynamic templates or inline HTML.
+
+## Using this package
+
+```ts
+module.exports = defineConfig({
+  modules: [
+    {
+      resolve: "@medusajs/medusa/notification",
+      options: {
+        providers: [
+          {
+            resolve: "@medusajs/medusa/notification-sendgrid",
+            id: "sendgrid",
+            options: {
+              channels: ["email"],
+              api_key: process.env.SENDGRID_API_KEY,
+              from: process.env.SENDGRID_FROM,
+            },
+          },
+        ],
+      },
+    },
+  ],
+})
+```
+
+- Options (`SendgridNotificationServiceOptions`): `api_key`, `from` (default sender). `channels` is read by the Notification Module.
+- Send with `Modules.NOTIFICATION` `createNotifications({ to, channel: "email", template, data })`; `template` is the SendGrid dynamic template ID and `data` becomes `dynamicTemplateData`.
+- Docs: https://docs.medusajs.com/resources/infrastructure-modules/notification/sendgrid.md
+- Build a custom notification provider: https://docs.medusajs.com/resources/references/notification-provider-module.md
+
+## Architecture
+
+- `src/services/sendgrid.ts`: `SendgridNotificationService extends AbstractNotificationProviderService`, `static identifier = "notification-sendgrid"`. Implements only `send`.
+- `sendgrid.setApiKey` is called in the constructor; `@sendgrid/mail` is a module-level singleton.
+- Reference for a custom email notification provider (attachments, per-notification `from`, `provider_data`).
+
+## Development
+
+- `yarn build`, `yarn test`
+- `yarn test:integration`: `integration-tests/__tests__/services.spec.ts` mocks `@sendgrid/mail` (no network).
+
+## Gotchas
+
+- If the notification has `content`, `content.subject` and `content.html` are sent and `template` is ignored (SendGrid can't mix HTML and templates). `content.text` is never sent.
+- `notification.from` overrides the configured `from` when non-empty.
+- `provider_data.personalizations` is passed straight to SendGrid and replaces the top-level `to`, so include recipients inside it.
+- Attachments: `content` must be base64; `disposition` defaults to `"attachment"`.
+- Errors are rethrown as `UNEXPECTED_STATE` with `Failed to send email: {code} - {SendGrid message}`; the notification is then marked failed.
+- No options validation: a missing `api_key` only surfaces when sending.
+- Only one provider per channel: don't also register `notification-local` for `email`.

package/README.md

@@ -0,0 +1,106 @@
+<p align="center">
+  <a href="https://www.medusajs.com">
+  <picture>
+    <source media="(prefers-color-scheme: dark)" srcset="https://user-images.githubusercontent.com/59018053/229103275-b5e482bb-4601-46e6-8142-244f531cebdb.svg">
+    <source media="(prefers-color-scheme: light)" srcset="https://user-images.githubusercontent.com/59018053/229103726-e5b529a3-9b3f-4970-8a1f-c6af37f087bf.svg">
+    <img alt="Medusa logo" src="https://user-images.githubusercontent.com/59018053/229103726-e5b529a3-9b3f-4970-8a1f-c6af37f087bf.svg">
+    </picture>
+  </a>
+</p>
+<h1 align="center">
+  @medusajs/notification-sendgrid
+</h1>
+
+<h4 align="center">
+  <a href="https://docs.medusajs.com">Documentation</a> |
+  <a href="https://www.medusajs.com">Website</a>
+</h4>
+
+<p align="center">
+  Building blocks for digital commerce
+</p>
+<p align="center">
+  <a href="https://github.com/medusajs/medusa/blob/develop/LICENSE">
+    <img src="https://img.shields.io/badge/license-MIT-blue.svg" alt="Medusa is released under the MIT license." />
+  </a>
+  <a href="https://github.com/medusajs/medusa/blob/develop/CONTRIBUTING.md">
+    <img src="https://img.shields.io/badge/PRs-welcome-brightgreen.svg?style=flat" alt="PRs welcome!" />
+  </a>
+  <a href="https://discord.gg/xpCwq3Kfn8">
+    <img src="https://img.shields.io/badge/chat-on%20discord-7289DA.svg" alt="Discord Chat" />
+  </a>
+  <a href="https://twitter.com/intent/follow?screen_name=medusajs">
+    <img src="https://img.shields.io/twitter/follow/medusajs.svg?label=Follow%20@medusajs" alt="Follow @medusajs" />
+  </a>
+</p>
+
+SendGrid Notification Module Provider for Medusa: sends email notifications through SendGrid, using SendGrid dynamic templates or raw HTML content. Use it to send transactional emails, such as order confirmations or password resets. It ships with `@medusajs/medusa` and is registered through the `@medusajs/medusa/notification-sendgrid` path.
+
+## At a glance
+
+| | |
+| --- | --- |
+| Package | `@medusajs/notification-sendgrid` |
+| Type | Module Provider (Notification Module) |
+| Provider ID | `notification-sendgrid` |
+| Registered by default | No |
+| Import from | `@medusajs/medusa/notification-sendgrid` |
+
+## Features
+
+- Sends a notification's `template` as a SendGrid dynamic template ID, with the notification's `data` as the template data.
+- Sends a notification's `content` (`subject` and `html`) instead of a template when it's set.
+- Supports attachments, a per-notification `from` address, and SendGrid `personalizations` through `provider_data`.
+
+## Installation
+
+No installation needed. The provider is a dependency of `@medusajs/medusa`.
+
+## Usage
+
+Register the provider in the Notification Module's `providers` array in `medusa-config.ts` for the `email` channel. Each channel can be handled by only one provider.
+
+```ts
+import { defineConfig } from "@medusajs/framework/utils"
+
+module.exports = defineConfig({
+  // ...
+  modules: [
+    {
+      resolve: "@medusajs/medusa/notification",
+      options: {
+        providers: [
+          {
+            resolve: "@medusajs/medusa/notification-sendgrid",
+            id: "sendgrid",
+            options: {
+              channels: ["email"],
+              api_key: process.env.SENDGRID_API_KEY,
+              from: process.env.SENDGRID_FROM,
+            },
+          },
+        ],
+      },
+    },
+  ],
+})
+```
+
+## Configuration
+
+| Option | Type | Description | Default |
+| --- | --- | --- | --- |
+| `channels` | `string[]` | Read by the Notification Module. The channels this provider handles; use `["email"]`. | `[]` |
+| `api_key` | `string` | Required. Your SendGrid API key. | - |
+| `from` | `string` | Required. The default sender email address. | - |
+
+| Environment variable | Description |
+| --- | --- |
+| `SENDGRID_API_KEY` | Value for `api_key`, as used in the example above. |
+| `SENDGRID_FROM` | Value for `from`, as used in the example above. |
+
+## Resources
+
+- [SendGrid Notification Module Provider](https://docs.medusajs.com/resources/infrastructure-modules/notification/sendgrid)
+- [Send Notifications](https://docs.medusajs.com/resources/infrastructure-modules/notification/send-notification)
+- [Notification Module](https://docs.medusajs.com/resources/infrastructure-modules/notification)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@medusajs/notification-sendgrid",
-  "version": "2.22.0-snapshot-20261020204851",
+  "version": "2.22.0",
   "description": "Sendgrid notification provider for Medusa",
   "main": "dist/index.js",
   "repository": {
@@ -13,10 +13,14 @@
   },
   "files": [
     "dist",
+    "AGENTS.md",
     "!dist/**/__tests__",
     "!dist/**/__mocks__",
     "!dist/**/__fixtures__"
   ],
+  "llms": "https://docs.medusajs.com/llms.txt",
+  "llmsFull": "https://docs.medusajs.com/llms-full.txt",
+  "mcpServer": "https://docs.medusajs.com/mcp",
   "engines": {
     "node": ">=22.22.0"
   },
@@ -29,13 +33,13 @@
     "watch": "yarn run -T tsc --watch"
   },
   "devDependencies": {
-    "@medusajs/framework": "2.22.0-snapshot-20261020204851"
+    "@medusajs/framework": "2.22.0"
   },
   "dependencies": {
     "@sendgrid/mail": "^8.1.6"
   },
   "peerDependencies": {
-    "@medusajs/framework": "2.22.0-snapshot-20261020204851"
+    "@medusajs/framework": "2.22.0"
   },
   "keywords": [
     "medusa-provider",