feat(mailer): add Resend provider (#3349)

* feat(mailer): add Resend provider alongside Nodemailer (#3309)

Add provider.resend.js wrapping the Resend SDK, register it in the
provider map, and document the config option (mailer.provider: 'resend'
+ mailer.options.apiKey). Default provider stays 'nodemailer' for
backward compatibility. Includes unit tests for both the provider
and the mailer index with Resend selected.

* fix(mailer): default provider to nodemailer and handle DEVKIT_NODE_ placeholders

* fix(mailer): add @returns tag to ResendProvider constructor JSDoc

* fix(mailer): add defensive fallback for Resend error message

Author: PierreBrisorgueil

config/defaults/development.config.js

@@ -109,14 +109,17 @@ const config = {
     sameSite: 'strict',
   },
   mailer: {
-    provider: 'DEVKIT_NODE_mailer_provider',
+    provider: 'nodemailer', // 'nodemailer' (default) or 'resend'
     from: 'DEVKIT_NODE_mailer_from',
     options: {
+      // nodemailer options
       service: 'DEVKIT_NODE_mailer_options_service',
       auth: {
         user: 'DEVKIT_NODE_mailer_options_auth_user',
         pass: 'DEVKIT_NODE_mailer_options_auth_pass',
       },
+      // resend options
+      apiKey: 'DEVKIT_NODE_mailer_options_apiKey',
     },
   },
   seedDB: {

lib/helpers/mailer/index.js

@@ -4,15 +4,17 @@ import handlebars from 'handlebars';
 import config from '../../../config/index.js';
 import files from '../files.js';
 import NodemailerProvider from './provider.nodemailer.js';
+import ResendProvider from './provider.resend.js';
 
-const providers = { nodemailer: NodemailerProvider };
+const providers = { nodemailer: NodemailerProvider, resend: ResendProvider };
 
 /**
  * @desc Create a mail provider instance based on config
  * @returns {Object} A mail provider with a send method
  */
 const createProvider = () => {
-  const providerName = config.mailer?.provider || 'nodemailer';
+  const raw = config.mailer?.provider;
+  const providerName = raw && !String(raw).startsWith('DEVKIT_NODE_') ? raw : 'nodemailer';
   const Provider = providers[providerName];
   if (!Provider) throw new Error(`Unknown mail provider: ${providerName}`);
   return new Provider(config.mailer.options);

lib/helpers/mailer/provider.resend.js

@@ -0,0 +1,29 @@
+import { Resend } from 'resend';
+
+export default class ResendProvider {
+  /**
+   * Create a Resend mail provider instance.
+   * @param {Object} options - Resend provider options
+   * @param {string} options.apiKey - Resend API key
+   * @returns {void}
+   */
+  constructor(options) {
+    if (!options?.apiKey) throw new Error('Resend provider requires an apiKey');
+    this.client = new Resend(options.apiKey);
+  }
+
+  /**
+   * @desc Send an email via Resend
+   * @param {Object} mail - Mail envelope
+   * @param {string} mail.from - Sender address
+   * @param {string} mail.to - Recipient address
+   * @param {string} mail.subject - Email subject
+   * @param {string} mail.html - HTML body
+   * @returns {Promise<Object>} Resend API response data
+   */
+  async send({ from, to, subject, html }) {
+    const { data, error } = await this.client.emails.send({ from, to, subject, html });
+    if (error) throw new Error(error.message || 'Resend API error');
+    return data;
+  }
+}

lib/helpers/mailer/tests/mailer.unit.tests.js

@@ -0,0 +1,76 @@
+/**
+ * Module dependencies.
+ */
+import { jest, describe, test, expect, beforeEach } from '@jest/globals';
+
+// Mock config, files, and providers before importing mailer
+jest.unstable_mockModule('../../../../config/index.js', () => ({
+  default: {
+    mailer: {
+      provider: 'resend',
+      from: 'test@example.com',
+      options: { apiKey: 're_test_123' },
+    },
+  },
+}));
+
+jest.unstable_mockModule('../../files.js', () => ({
+  default: {
+    readFile: jest.fn().mockResolvedValue('<p>{{name}}</p>'),
+  },
+}));
+
+const mockSend = jest.fn().mockResolvedValue({ id: 'email_123' });
+jest.unstable_mockModule('../provider.resend.js', () => ({
+  default: jest.fn().mockImplementation(() => ({ send: mockSend })),
+}));
+
+jest.unstable_mockModule('../provider.nodemailer.js', () => ({
+  default: jest.fn().mockImplementation(() => ({ send: jest.fn() })),
+}));
+
+const { default: mailer } = await import('../index.js');
+
+describe('mailer index with resend provider unit tests:', () => {
+  beforeEach(() => {
+    jest.clearAllMocks();
+  });
+
+  test('should report as configured when from is set', () => {
+    expect(mailer.isConfigured()).toBe(true);
+  });
+
+  test('should send mail using the resend provider', async () => {
+    mockSend.mockResolvedValue({ id: 'email_456' });
+
+    const result = await mailer.sendMail({
+      to: 'user@example.com',
+      subject: 'Welcome',
+      template: 'welcome',
+      params: { name: 'Alice' },
+    });
+
+    expect(mockSend).toHaveBeenCalledWith(
+      expect.objectContaining({
+        from: 'test@example.com',
+        to: 'user@example.com',
+        subject: 'Welcome',
+        html: '<p>Alice</p>',
+      }),
+    );
+    expect(result).toEqual({ id: 'email_456' });
+  });
+
+  test('should return null on send error', async () => {
+    mockSend.mockRejectedValue(new Error('API failure'));
+
+    const result = await mailer.sendMail({
+      to: 'user@example.com',
+      subject: 'Test',
+      template: 'welcome',
+      params: { name: 'Bob' },
+    });
+
+    expect(result).toBeNull();
+  });
+});

lib/helpers/mailer/tests/provider.resend.unit.tests.js

@@ -0,0 +1,72 @@
+/**
+ * Module dependencies.
+ */
+import { jest, describe, test, expect, beforeEach } from '@jest/globals';
+
+// Mock resend before importing the provider
+jest.unstable_mockModule('resend', () => ({
+  Resend: jest.fn().mockImplementation(() => ({
+    emails: {
+      send: jest.fn(),
+    },
+  })),
+}));
+
+const { Resend } = await import('resend');
+const { default: ResendProvider } = await import('../provider.resend.js');
+
+describe('ResendProvider unit tests:', () => {
+  let provider;
+  let sendMock;
+
+  beforeEach(() => {
+    jest.clearAllMocks();
+    sendMock = jest.fn();
+    Resend.mockImplementation(() => ({
+      emails: { send: sendMock },
+    }));
+    provider = new ResendProvider({ apiKey: 're_test_123' });
+  });
+
+  test('should throw if apiKey is missing', () => {
+    expect(() => new ResendProvider({})).toThrow('Resend provider requires an apiKey');
+    expect(() => new ResendProvider()).toThrow('Resend provider requires an apiKey');
+  });
+
+  test('should create a Resend client with the provided apiKey', () => {
+    expect(Resend).toHaveBeenCalledWith('re_test_123');
+  });
+
+  test('should send an email successfully', async () => {
+    const mockData = { id: 'email_123' };
+    sendMock.mockResolvedValue({ data: mockData, error: null });
+
+    const result = await provider.send({
+      from: 'sender@example.com',
+      to: 'recipient@example.com',
+      subject: 'Test',
+      html: '<p>Hello</p>',
+    });
+
+    expect(sendMock).toHaveBeenCalledWith({
+      from: 'sender@example.com',
+      to: 'recipient@example.com',
+      subject: 'Test',
+      html: '<p>Hello</p>',
+    });
+    expect(result).toEqual(mockData);
+  });
+
+  test('should throw on Resend API error', async () => {
+    sendMock.mockResolvedValue({ data: null, error: { message: 'Invalid API key' } });
+
+    await expect(
+      provider.send({
+        from: 'sender@example.com',
+        to: 'recipient@example.com',
+        subject: 'Test',
+        html: '<p>Hello</p>',
+      }),
+    ).rejects.toThrow('Invalid API key');
+  });
+});