@flusys/nestjs-email 6.0.2 → 6.1.1

package/fesm/providers/sendgrid-provider.spec.js

@@ -0,0 +1,342 @@
+import { InternalServerErrorException } from '@nestjs/common';
+import { SendGridProvider } from './sendgrid-provider';
+// @sendgrid/mail is not an installed dependency in this workspace, so the real dynamic
+// import() inside `initialize()` fails — exercised directly, no mocking needed.
+// For "happy path" behavior we bypass initialize() and inject a fake sgMail client,
+// matching the private `sgMail`/`apiKey` fields the provider mutates internally.
+function injectSgMail(provider, sgMail, apiKey = 'SG.fake-key') {
+    provider.sgMail = sgMail;
+    provider.apiKey = apiKey;
+}
+describe('SendGridProvider', ()=>{
+    let provider;
+    beforeEach(()=>{
+        provider = new SendGridProvider();
+    });
+    describe('initialize', ()=>{
+        it('throws InternalServerErrorException with SDK_NOT_INSTALLED when @sendgrid/mail is unavailable', async ()=>{
+            await expect(provider.initialize({
+                apiKey: 'SG.key'
+            })).rejects.toThrow(InternalServerErrorException);
+        });
+        it('surfaces the sdk name in the exception messageVariables', async ()=>{
+            try {
+                await provider.initialize({
+                    apiKey: 'SG.key'
+                });
+                fail('expected initialize to throw');
+            } catch (error) {
+                expect(error.getResponse()).toEqual(expect.objectContaining({
+                    messageKey: 'system.sdk.not.installed',
+                    messageVariables: {
+                        sdk: 'sendgrid'
+                    }
+                }));
+            }
+        });
+    });
+    describe('sendEmail', ()=>{
+        it('returns a failure result when the provider was never initialized', async ()=>{
+            const result = await provider.sendEmail({
+                to: 'a@example.com',
+                subject: 'Hi'
+            });
+            expect(result).toEqual({
+                success: false,
+                error: 'SendGrid provider not initialized'
+            });
+        });
+        it('sends via sgMail.send and extracts the message id from response headers', async ()=>{
+            const send = jest.fn().mockResolvedValue([
+                {
+                    headers: {
+                        'x-message-id': 'sg-msg-1'
+                    }
+                }
+            ]);
+            injectSgMail(provider, {
+                send
+            });
+            const result = await provider.sendEmail({
+                to: [
+                    'a@example.com',
+                    'b@example.com'
+                ],
+                subject: 'Hello',
+                html: '<p>hi</p>',
+                from: 'sender@example.com',
+                fromName: 'Sender Name',
+                cc: 'c@example.com',
+                bcc: [
+                    'd@example.com'
+                ],
+                replyTo: 'reply@example.com'
+            });
+            expect(result).toEqual({
+                success: true,
+                messageId: 'sg-msg-1'
+            });
+            expect(send).toHaveBeenCalledWith(expect.objectContaining({
+                to: [
+                    'a@example.com',
+                    'b@example.com'
+                ],
+                from: {
+                    email: 'sender@example.com',
+                    name: 'Sender Name'
+                },
+                subject: 'Hello',
+                html: '<p>hi</p>',
+                cc: [
+                    'c@example.com'
+                ],
+                bcc: [
+                    'd@example.com'
+                ],
+                replyTo: 'reply@example.com'
+            }));
+        });
+        it('falls back to the capitalized X-Message-Id header when lowercase is absent', async ()=>{
+            const send = jest.fn().mockResolvedValue([
+                {
+                    headers: {
+                        'X-Message-Id': 'sg-msg-2'
+                    }
+                }
+            ]);
+            injectSgMail(provider, {
+                send
+            });
+            const result = await provider.sendEmail({
+                to: 'a@example.com',
+                subject: 'Hi',
+                from: 'x@example.com'
+            });
+            expect(result).toEqual({
+                success: true,
+                messageId: 'sg-msg-2'
+            });
+        });
+        it('base64-encodes buffer attachment content for the SendGrid payload', async ()=>{
+            const send = jest.fn().mockResolvedValue([
+                {
+                    headers: {}
+                }
+            ]);
+            injectSgMail(provider, {
+                send
+            });
+            await provider.sendEmail({
+                to: 'a@example.com',
+                subject: 'Hi',
+                from: 'x@example.com',
+                attachments: [
+                    {
+                        filename: 'doc.txt',
+                        content: Buffer.from('hello'),
+                        contentType: 'text/plain'
+                    }
+                ]
+            });
+            const [msg] = send.mock.calls[0];
+            expect(msg.attachments[0]).toEqual({
+                filename: 'doc.txt',
+                content: Buffer.from('hello').toString('base64'),
+                type: 'text/plain',
+                disposition: 'attachment'
+            });
+        });
+        it('returns the SendGrid API error message on failure', async ()=>{
+            injectSgMail(provider, {
+                send: jest.fn().mockRejectedValue({
+                    response: {
+                        body: {
+                            errors: [
+                                {
+                                    message: 'Invalid recipient'
+                                }
+                            ]
+                        }
+                    }
+                })
+            });
+            const result = await provider.sendEmail({
+                to: 'a@example.com',
+                subject: 'Hi'
+            });
+            expect(result).toEqual({
+                success: false,
+                error: 'Invalid recipient'
+            });
+        });
+        it('falls back to the generic error message when no SendGrid error body is present', async ()=>{
+            injectSgMail(provider, {
+                send: jest.fn().mockRejectedValue(new Error('network down'))
+            });
+            const result = await provider.sendEmail({
+                to: 'a@example.com',
+                subject: 'Hi'
+            });
+            expect(result).toEqual({
+                success: false,
+                error: 'network down'
+            });
+        });
+        it('falls back to "Unknown error" when no message is available at all', async ()=>{
+            injectSgMail(provider, {
+                send: jest.fn().mockRejectedValue({})
+            });
+            const result = await provider.sendEmail({
+                to: 'a@example.com',
+                subject: 'Hi'
+            });
+            expect(result).toEqual({
+                success: false,
+                error: 'Unknown error'
+            });
+        });
+    });
+    describe('sendBulkEmails', ()=>{
+        it('returns a not-initialized failure per message when not initialized', async ()=>{
+            const results = await provider.sendBulkEmails([
+                {
+                    to: 'a@example.com',
+                    subject: 'A'
+                },
+                {
+                    to: 'b@example.com',
+                    subject: 'B'
+                }
+            ]);
+            expect(results).toEqual([
+                {
+                    success: false,
+                    error: 'SendGrid provider not initialized'
+                },
+                {
+                    success: false,
+                    error: 'SendGrid provider not initialized'
+                }
+            ]);
+        });
+        it('sends all messages in a single sgMail.send call and reports success for all', async ()=>{
+            const send = jest.fn().mockResolvedValue(undefined);
+            injectSgMail(provider, {
+                send
+            });
+            const results = await provider.sendBulkEmails([
+                {
+                    to: 'a@example.com',
+                    subject: 'A',
+                    from: 'x@example.com'
+                },
+                {
+                    to: 'b@example.com',
+                    subject: 'B',
+                    from: 'x@example.com'
+                }
+            ]);
+            expect(send).toHaveBeenCalledTimes(1);
+            expect(send).toHaveBeenCalledWith([
+                expect.objectContaining({
+                    to: [
+                        'a@example.com'
+                    ],
+                    subject: 'A'
+                }),
+                expect.objectContaining({
+                    to: [
+                        'b@example.com'
+                    ],
+                    subject: 'B'
+                })
+            ]);
+            expect(results).toEqual([
+                {
+                    success: true
+                },
+                {
+                    success: true
+                }
+            ]);
+        });
+        it('excludes cc/bcc/replyTo/attachments from bulk messages (includeExtras=false)', async ()=>{
+            const send = jest.fn().mockResolvedValue(undefined);
+            injectSgMail(provider, {
+                send
+            });
+            await provider.sendBulkEmails([
+                {
+                    to: 'a@example.com',
+                    subject: 'A',
+                    from: 'x@example.com',
+                    cc: 'c@example.com',
+                    replyTo: 'r@example.com'
+                }
+            ]);
+            const [messages] = send.mock.calls[0];
+            expect(messages[0]).not.toHaveProperty('cc');
+            expect(messages[0]).not.toHaveProperty('replyTo');
+        });
+        it('reports the same failure for every message when the bulk send call rejects', async ()=>{
+            injectSgMail(provider, {
+                send: jest.fn().mockRejectedValue(new Error('rate limited'))
+            });
+            const results = await provider.sendBulkEmails([
+                {
+                    to: 'a@example.com',
+                    subject: 'A',
+                    from: 'x@example.com'
+                },
+                {
+                    to: 'b@example.com',
+                    subject: 'B',
+                    from: 'x@example.com'
+                }
+            ]);
+            expect(results).toEqual([
+                {
+                    success: false,
+                    error: 'rate limited'
+                },
+                {
+                    success: false,
+                    error: 'rate limited'
+                }
+            ]);
+        });
+    });
+    describe('healthCheck', ()=>{
+        it('returns false when not initialized', async ()=>{
+            await expect(provider.healthCheck()).resolves.toBe(false);
+        });
+        it('returns true when sgMail is set and the api key has the SG. prefix', async ()=>{
+            injectSgMail(provider, {
+                send: jest.fn()
+            }, 'SG.validkey');
+            await expect(provider.healthCheck()).resolves.toBe(true);
+        });
+        it('returns false when the api key does not have the SG. prefix', async ()=>{
+            injectSgMail(provider, {
+                send: jest.fn()
+            }, 'invalid-key');
+            await expect(provider.healthCheck()).resolves.toBe(false);
+        });
+    });
+    describe('close', ()=>{
+        it('clears the sgMail client reference', async ()=>{
+            injectSgMail(provider, {
+                send: jest.fn()
+            });
+            await provider.close();
+            const result = await provider.sendEmail({
+                to: 'a@example.com',
+                subject: 'Hi'
+            });
+            expect(result).toEqual({
+                success: false,
+                error: 'SendGrid provider not initialized'
+            });
+        });
+    });
+});

package/fesm/providers/smtp-provider.js

@@ -94,11 +94,18 @@ export class SmtpProvider {
         return Array.isArray(addresses) ? addresses.join(', ') : addresses;
     }
     async withTimeout(promise, ms, message) {
-        const timeout = new Promise((_, reject)=>setTimeout(()=>reject(new Error(message)), ms));
-        return Promise.race([
-            promise,
-            timeout
-        ]);
+        let timer;
+        const timeout = new Promise((_, reject)=>{
+            timer = setTimeout(()=>reject(new Error(message)), ms);
+        });
+        try {
+            return await Promise.race([
+                promise,
+                timeout
+            ]);
+        } finally{
+            clearTimeout(timer);
+        }
     }
     extractError(error) {
         return error instanceof Error ? error.message : 'Unknown error';

package/fesm/providers/smtp-provider.spec.js

@@ -0,0 +1,282 @@
+const mockTransporter = {
+    verify: jest.fn(),
+    sendMail: jest.fn(),
+    close: jest.fn()
+};
+jest.mock('nodemailer', ()=>({
+        createTransport: jest.fn()
+    }));
+import * as nodemailer from 'nodemailer';
+import { SmtpProvider } from './smtp-provider';
+const createTransport = nodemailer.createTransport;
+createTransport.mockReturnValue(mockTransporter);
+function injectTransporter(provider, transporter) {
+    provider.transporter = transporter;
+}
+describe('SmtpProvider', ()=>{
+    let provider;
+    beforeEach(()=>{
+        provider = new SmtpProvider();
+        jest.clearAllMocks();
+    });
+    describe('initialize', ()=>{
+        it('creates a nodemailer transport with the given config and verifies the connection', async ()=>{
+            mockTransporter.verify.mockResolvedValue(true);
+            await provider.initialize({
+                host: 'smtp.example.com',
+                port: 587,
+                auth: {
+                    user: 'user',
+                    pass: 'pass'
+                }
+            });
+            expect(createTransport).toHaveBeenCalledWith(expect.objectContaining({
+                host: 'smtp.example.com',
+                port: 587,
+                secure: false,
+                auth: {
+                    user: 'user',
+                    pass: 'pass'
+                },
+                tls: expect.objectContaining({
+                    rejectUnauthorized: true,
+                    minVersion: 'TLSv1.2'
+                })
+            }));
+            expect(mockTransporter.verify).toHaveBeenCalled();
+        });
+        it('defaults secure=true when port is 465 and secure is not explicitly set', async ()=>{
+            mockTransporter.verify.mockResolvedValue(true);
+            await provider.initialize({
+                host: 'smtp.example.com',
+                port: 465
+            });
+            expect(createTransport).toHaveBeenCalledWith(expect.objectContaining({
+                secure: true
+            }));
+        });
+        it('honors an explicit secure flag over the port-based default', async ()=>{
+            mockTransporter.verify.mockResolvedValue(true);
+            await provider.initialize({
+                host: 'smtp.example.com',
+                port: 587,
+                secure: true
+            });
+            expect(createTransport).toHaveBeenCalledWith(expect.objectContaining({
+                secure: true
+            }));
+        });
+        it('allows disabling TLS certificate validation via config', async ()=>{
+            mockTransporter.verify.mockResolvedValue(true);
+            await provider.initialize({
+                host: 'smtp.example.com',
+                port: 587,
+                tls: {
+                    rejectUnauthorized: false
+                }
+            });
+            expect(createTransport).toHaveBeenCalledWith(expect.objectContaining({
+                tls: expect.objectContaining({
+                    rejectUnauthorized: false
+                })
+            }));
+        });
+        it('propagates a connection verification failure', async ()=>{
+            mockTransporter.verify.mockRejectedValue(new Error('ECONNREFUSED'));
+            await expect(provider.initialize({
+                host: 'smtp.example.com',
+                port: 587
+            })).rejects.toThrow('ECONNREFUSED');
+        });
+    });
+    describe('sendEmail', ()=>{
+        it('returns a failure result when the provider was never initialized', async ()=>{
+            const result = await provider.sendEmail({
+                to: 'a@example.com',
+                subject: 'Hi'
+            });
+            expect(result).toEqual({
+                success: false,
+                error: 'SMTP provider not initialized'
+            });
+        });
+        it('sends mail via the transporter and returns the message id', async ()=>{
+            injectTransporter(provider, mockTransporter);
+            mockTransporter.sendMail.mockResolvedValue({
+                messageId: 'msg-1'
+            });
+            const result = await provider.sendEmail({
+                to: [
+                    'a@example.com',
+                    'b@example.com'
+                ],
+                cc: 'c@example.com',
+                bcc: [
+                    'd@example.com'
+                ],
+                subject: 'Hello',
+                html: '<p>hi</p>',
+                text: 'hi',
+                from: 'sender@example.com',
+                fromName: 'Sender Name',
+                replyTo: 'reply@example.com'
+            });
+            expect(result).toEqual({
+                success: true,
+                messageId: 'msg-1'
+            });
+            expect(mockTransporter.sendMail).toHaveBeenCalledWith(expect.objectContaining({
+                from: '"Sender Name" <sender@example.com>',
+                to: 'a@example.com, b@example.com',
+                cc: 'c@example.com',
+                bcc: 'd@example.com',
+                subject: 'Hello',
+                html: '<p>hi</p>',
+                text: 'hi',
+                replyTo: 'reply@example.com'
+            }));
+        });
+        it('sends the bare "from" address when fromName is not provided', async ()=>{
+            injectTransporter(provider, mockTransporter);
+            mockTransporter.sendMail.mockResolvedValue({
+                messageId: 'msg-1'
+            });
+            await provider.sendEmail({
+                to: 'a@example.com',
+                subject: 'Hi',
+                from: 'sender@example.com'
+            });
+            expect(mockTransporter.sendMail).toHaveBeenCalledWith(expect.objectContaining({
+                from: 'sender@example.com'
+            }));
+        });
+        it('maps attachments through to nodemailer mail options', async ()=>{
+            injectTransporter(provider, mockTransporter);
+            mockTransporter.sendMail.mockResolvedValue({
+                messageId: 'msg-1'
+            });
+            await provider.sendEmail({
+                to: 'a@example.com',
+                subject: 'Hi',
+                attachments: [
+                    {
+                        filename: 'doc.txt',
+                        content: Buffer.from('hi'),
+                        contentType: 'text/plain'
+                    }
+                ]
+            });
+            const [mailOptions] = mockTransporter.sendMail.mock.calls[0];
+            expect(mailOptions.attachments).toEqual([
+                {
+                    filename: 'doc.txt',
+                    content: Buffer.from('hi'),
+                    contentType: 'text/plain',
+                    encoding: undefined
+                }
+            ]);
+        });
+        it('returns the error message when sendMail rejects with an Error', async ()=>{
+            injectTransporter(provider, mockTransporter);
+            mockTransporter.sendMail.mockRejectedValue(new Error('Connection refused'));
+            const result = await provider.sendEmail({
+                to: 'a@example.com',
+                subject: 'Hi'
+            });
+            expect(result).toEqual({
+                success: false,
+                error: 'Connection refused'
+            });
+        });
+        it('returns "Unknown error" when sendMail rejects with a non-Error', async ()=>{
+            injectTransporter(provider, mockTransporter);
+            mockTransporter.sendMail.mockRejectedValue('raw string failure');
+            const result = await provider.sendEmail({
+                to: 'a@example.com',
+                subject: 'Hi'
+            });
+            expect(result).toEqual({
+                success: false,
+                error: 'Unknown error'
+            });
+        });
+        it('surfaces a timeout error if sendMail never settles before the send timeout', async ()=>{
+            jest.useFakeTimers();
+            injectTransporter(provider, mockTransporter);
+            mockTransporter.sendMail.mockReturnValue(new Promise(()=>{}));
+            const pending = provider.sendEmail({
+                to: 'a@example.com',
+                subject: 'Hi'
+            });
+            jest.advanceTimersByTime(30_000);
+            const result = await pending;
+            expect(result).toEqual({
+                success: false,
+                error: 'SMTP send timeout'
+            });
+            jest.useRealTimers();
+        });
+    });
+    describe('sendBulkEmails', ()=>{
+        it('sends each message individually and aggregates the results', async ()=>{
+            injectTransporter(provider, mockTransporter);
+            mockTransporter.sendMail.mockResolvedValueOnce({
+                messageId: 'id-1'
+            }).mockRejectedValueOnce(new Error('failed-2'));
+            const results = await provider.sendBulkEmails([
+                {
+                    to: 'a@example.com',
+                    subject: 'A'
+                },
+                {
+                    to: 'b@example.com',
+                    subject: 'B'
+                }
+            ]);
+            expect(results).toEqual([
+                {
+                    success: true,
+                    messageId: 'id-1'
+                },
+                {
+                    success: false,
+                    error: 'failed-2'
+                }
+            ]);
+        });
+    });
+    describe('healthCheck', ()=>{
+        it('returns false when not initialized', async ()=>{
+            await expect(provider.healthCheck()).resolves.toBe(false);
+        });
+        it('returns true when transporter.verify() resolves', async ()=>{
+            injectTransporter(provider, mockTransporter);
+            mockTransporter.verify.mockResolvedValue(true);
+            await expect(provider.healthCheck()).resolves.toBe(true);
+        });
+        it('returns false when transporter.verify() rejects', async ()=>{
+            injectTransporter(provider, mockTransporter);
+            mockTransporter.verify.mockRejectedValue(new Error('down'));
+            await expect(provider.healthCheck()).resolves.toBe(false);
+        });
+    });
+    describe('close', ()=>{
+        it('closes and clears the transporter', async ()=>{
+            injectTransporter(provider, mockTransporter);
+            await provider.close();
+            expect(mockTransporter.close).toHaveBeenCalled();
+            const result = await provider.sendEmail({
+                to: 'a@example.com',
+                subject: 'Hi'
+            });
+            expect(result).toEqual({
+                success: false,
+                error: 'SMTP provider not initialized'
+            });
+        });
+        it('is a no-op when no transporter exists', async ()=>{
+            await expect(provider.close()).resolves.toBeUndefined();
+            expect(mockTransporter.close).not.toHaveBeenCalled();
+        });
+    });
+});