feat(messaging): extend messaging to email with SendGrid adapter (@quatrain/messaging-sendgrid) #19

Open
opened 2026-10-27 14:51:27 +00:00 by crapougnax · 0 comments
Owner

Migrated from GitHub https://github.com/Quatrain/Core/issues/51 (opened by @crapougnax on 2026-09-21).

🎯 Goal

Extend the @quatrain/messaging ecosystem to support transactional emails by creating a dedicated SendGrid adapter package: @quatrain/messaging-sendgrid.

📋 Context & Motivation

Currently, @quatrain/messaging defines the EmailCapableAdapter interface (sendEmail and sendEmails), but lacks a production-ready email adapter implementation (only @quatrain/messaging-firebase exists, which focuses on push notifications).

Consuming backend applications currently interact directly with @sendgrid/mail outside of the unified Quatrain messaging abstraction layer. Providing @quatrain/messaging-sendgrid will:

  • Standardize transactional email sending across the Quatrain ecosystem.
  • Enable clean dependency injection, mockability in tests, and provider swapping.

🛠️ Proposed Architecture & Specifications

  1. New Package Creation:

    • Location: packages/messaging-sendgrid
    • Package name: @quatrain/messaging-sendgrid
    • License: AGPL-3.0-only
    • Repository block pointing to git+https://github.com/Quatrain/Core.git with "directory": "packages/messaging-sendgrid"
  2. Adapter Implementation:

    • Class SendgridMessagingAdapter extending AbstractMessagingAdapter and implementing EmailCapableAdapter.
    • Implement sendEmail(recipient: MessagingRecipient, message: NotificationMessage): Promise<any>.
    • Implement sendEmails(recipients: MessagingRecipient[], message: NotificationMessage): Promise<any>.
  3. Configuration & Parameters:

    • Interface SendgridMessagingParameters extending MessagingParameters:
      • apiKey: SendGrid API key (fail-fast validation in constructor).
      • defaultSender: Default "From" email and optional display name.
      • sandboxMode / debug: Boolean flag for development/dry-run mode without sending real emails.
  4. Message Formatting & Capabilities:

    • Support plain text and HTML bodies.
    • Support template substitution and recipient personalization.
    • Support CC, BCC, and custom reply-to headers.
    • Strict typing with zero as any bypasses.
  5. Logging & Error Handling:

    • Scoped logger using this.addLogger('Messaging:SendGrid').
    • Meaningful error reporting and status mapping for API failures (rate limits, authentication, invalid payloads).
  6. Documentation & Quality Gates:

    • Comprehensive README.md and HOWTO.md with usage examples.
    • Strict TypeScript compilation (tsc -p tsconfig.json with 0 errors).
    • Co-located unit tests (SendgridMessagingAdapter.test.ts) with high test coverage and mocked @sendgrid/mail.
    • Clean .npmignore and package.json "files" entry excluding all test files and configs.

🧪 Acceptance Criteria

  • @quatrain/messaging-sendgrid created in packages/messaging-sendgrid.
  • Implements EmailCapableAdapter contract adhering to Quatrain architectural standards.
  • Constructor validates mandatory credentials and fails fast on configuration errors.
  • Single and batch email transmissions pass automated unit tests with mocks.
  • Workspace builds cleanly (turbo run build).
  • Package includes README.md, HOWTO.md, clean package.json, and .npmignore.
> Migrated from GitHub https://github.com/Quatrain/Core/issues/51 (opened by @crapougnax on 2026-09-21). ### 🎯 Goal Extend the `@quatrain/messaging` ecosystem to support transactional emails by creating a dedicated SendGrid adapter package: `@quatrain/messaging-sendgrid`. ### 📋 Context & Motivation Currently, `@quatrain/messaging` defines the `EmailCapableAdapter` interface (`sendEmail` and `sendEmails`), but lacks a production-ready email adapter implementation (only `@quatrain/messaging-firebase` exists, which focuses on push notifications). Consuming backend applications currently interact directly with `@sendgrid/mail` outside of the unified Quatrain messaging abstraction layer. Providing `@quatrain/messaging-sendgrid` will: - Standardize transactional email sending across the Quatrain ecosystem. - Enable clean dependency injection, mockability in tests, and provider swapping. ### 🛠️ Proposed Architecture & Specifications 1. **New Package Creation**: - Location: `packages/messaging-sendgrid` - Package name: `@quatrain/messaging-sendgrid` - License: AGPL-3.0-only - Repository block pointing to `git+https://github.com/Quatrain/Core.git` with `"directory": "packages/messaging-sendgrid"` 2. **Adapter Implementation**: - Class `SendgridMessagingAdapter` extending `AbstractMessagingAdapter` and implementing `EmailCapableAdapter`. - Implement `sendEmail(recipient: MessagingRecipient, message: NotificationMessage): Promise<any>`. - Implement `sendEmails(recipients: MessagingRecipient[], message: NotificationMessage): Promise<any>`. 3. **Configuration & Parameters**: - Interface `SendgridMessagingParameters` extending `MessagingParameters`: - `apiKey`: SendGrid API key (fail-fast validation in constructor). - `defaultSender`: Default "From" email and optional display name. - `sandboxMode` / `debug`: Boolean flag for development/dry-run mode without sending real emails. 4. **Message Formatting & Capabilities**: - Support plain text and HTML bodies. - Support template substitution and recipient personalization. - Support CC, BCC, and custom reply-to headers. - Strict typing with zero `as any` bypasses. 5. **Logging & Error Handling**: - Scoped logger using `this.addLogger('Messaging:SendGrid')`. - Meaningful error reporting and status mapping for API failures (rate limits, authentication, invalid payloads). 6. **Documentation & Quality Gates**: - Comprehensive `README.md` and `HOWTO.md` with usage examples. - Strict TypeScript compilation (`tsc -p tsconfig.json` with 0 errors). - Co-located unit tests (`SendgridMessagingAdapter.test.ts`) with high test coverage and mocked `@sendgrid/mail`. - Clean `.npmignore` and `package.json` `"files"` entry excluding all test files and configs. ### 🧪 Acceptance Criteria - [ ] `@quatrain/messaging-sendgrid` created in `packages/messaging-sendgrid`. - [ ] Implements `EmailCapableAdapter` contract adhering to Quatrain architectural standards. - [ ] Constructor validates mandatory credentials and fails fast on configuration errors. - [ ] Single and batch email transmissions pass automated unit tests with mocks. - [ ] Workspace builds cleanly (`turbo run build`). - [ ] Package includes `README.md`, `HOWTO.md`, clean `package.json`, and `.npmignore`.
Sign in to join this conversation.
No milestone
No project
No assignees
1 participant
Notifications
Due date
The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Dependencies

No dependencies set.

Reference
quatrain/core#19
No description provided.