@flusys/nestjs-email 6.0.1 → 6.1.0

package/cjs/providers/email-factory.service.spec.js

@@ -0,0 +1,242 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", {
+    value: true
+});
+const _common = require("@nestjs/common");
+const _emailfactoryservice = require("./email-factory.service");
+const _emailproviderregistry = require("./email-provider.registry");
+function _define_property(obj, key, value) {
+    if (key in obj) {
+        Object.defineProperty(obj, key, {
+            value: value,
+            enumerable: true,
+            configurable: true,
+            writable: true
+        });
+    } else {
+        obj[key] = value;
+    }
+    return obj;
+}
+let FakeSuccessProvider = class FakeSuccessProvider {
+    async initialize(_config) {
+        FakeSuccessProvider.initializeCalls += 1;
+    }
+    async sendEmail(_options) {
+        return {
+            success: true
+        };
+    }
+    async sendBulkEmails(_options) {
+        return [];
+    }
+    async healthCheck() {
+        return true;
+    }
+    async close() {
+        this.closeCalled = true;
+    }
+    constructor(){
+        _define_property(this, "closeCalled", false);
+        FakeSuccessProvider.instances.push(this);
+    }
+};
+_define_property(FakeSuccessProvider, "initializeCalls", 0);
+_define_property(FakeSuccessProvider, "instances", []);
+let FakeFailingInitProvider = class FakeFailingInitProvider {
+    async initialize(_config) {
+        throw new Error('boom during init');
+    }
+    async sendEmail(_options) {
+        return {
+            success: true
+        };
+    }
+    async sendBulkEmails(_options) {
+        return [];
+    }
+    async healthCheck() {
+        return true;
+    }
+};
+let FakeNoInitializeProvider = class FakeNoInitializeProvider {
+    async sendEmail(_options) {
+        return {
+            success: true
+        };
+    }
+    async sendBulkEmails(_options) {
+        return [];
+    }
+    async healthCheck() {
+        return true;
+    }
+};
+describe('EmailFactoryService', ()=>{
+    let service;
+    beforeEach(()=>{
+        service = new _emailfactoryservice.EmailFactoryService();
+        _emailproviderregistry.EmailProviderRegistry.clear();
+        FakeSuccessProvider.initializeCalls = 0;
+        FakeSuccessProvider.instances = [];
+    });
+    afterEach(()=>{
+        _emailproviderregistry.EmailProviderRegistry.clear();
+    });
+    describe('createProvider', ()=>{
+        it('throws NotFoundException when the provider is not registered', async ()=>{
+            const config = {
+                provider: 'unknown',
+                config: {}
+            };
+            await expect(service.createProvider(config)).rejects.toThrow(_common.NotFoundException);
+        });
+        it('throws NotFoundException with the config-not-found messageKey and available list', async ()=>{
+            _emailproviderregistry.EmailProviderRegistry.register('smtp', FakeSuccessProvider);
+            const config = {
+                provider: 'unknown',
+                config: {}
+            };
+            try {
+                await service.createProvider(config);
+                fail('expected createProvider to throw');
+            } catch (error) {
+                expect(error).toBeInstanceOf(_common.NotFoundException);
+                expect(error.getResponse()).toEqual(expect.objectContaining({
+                    messageKey: 'email.send.config.not.found'
+                }));
+            }
+        });
+        it('instantiates and initializes the provider on cache miss', async ()=>{
+            _emailproviderregistry.EmailProviderRegistry.register('smtp', FakeSuccessProvider);
+            const config = {
+                provider: 'smtp',
+                config: {
+                    host: 'localhost'
+                }
+            };
+            const provider = await service.createProvider(config);
+            expect(provider).toBeInstanceOf(FakeSuccessProvider);
+            expect(FakeSuccessProvider.initializeCalls).toBe(1);
+        });
+        it('returns the cached provider instance for an identical config (no re-initialization)', async ()=>{
+            _emailproviderregistry.EmailProviderRegistry.register('smtp', FakeSuccessProvider);
+            const config = {
+                provider: 'smtp',
+                config: {
+                    host: 'localhost'
+                }
+            };
+            const first = await service.createProvider(config);
+            const second = await service.createProvider(config);
+            expect(second).toBe(first);
+            expect(FakeSuccessProvider.initializeCalls).toBe(1);
+        });
+        it('creates a distinct cached instance for a different config on the same provider', async ()=>{
+            _emailproviderregistry.EmailProviderRegistry.register('smtp', FakeSuccessProvider);
+            const first = await service.createProvider({
+                provider: 'smtp',
+                config: {
+                    host: 'a'
+                }
+            });
+            const second = await service.createProvider({
+                provider: 'smtp',
+                config: {
+                    host: 'b'
+                }
+            });
+            expect(second).not.toBe(first);
+            expect(FakeSuccessProvider.initializeCalls).toBe(2);
+        });
+        it('is insensitive to key ordering when hashing the config for the cache key', async ()=>{
+            _emailproviderregistry.EmailProviderRegistry.register('smtp', FakeSuccessProvider);
+            const first = await service.createProvider({
+                provider: 'smtp',
+                config: {
+                    a: 1,
+                    b: 2
+                }
+            });
+            const second = await service.createProvider({
+                provider: 'smtp',
+                config: {
+                    b: 2,
+                    a: 1
+                }
+            });
+            expect(second).toBe(first);
+            expect(FakeSuccessProvider.initializeCalls).toBe(1);
+        });
+        it('does not call initialize when the provider class has no initialize method', async ()=>{
+            _emailproviderregistry.EmailProviderRegistry.register('smtp', FakeNoInitializeProvider);
+            const config = {
+                provider: 'smtp',
+                config: {}
+            };
+            const provider = await service.createProvider(config);
+            expect(provider).toBeInstanceOf(FakeNoInitializeProvider);
+        });
+        it('wraps initialize() failures in InternalServerErrorException with SDK_NOT_INSTALLED messageKey', async ()=>{
+            _emailproviderregistry.EmailProviderRegistry.register('mailgun', FakeFailingInitProvider);
+            const config = {
+                provider: 'mailgun',
+                config: {}
+            };
+            try {
+                await service.createProvider(config);
+                fail('expected createProvider to throw');
+            } catch (error) {
+                expect(error).toBeInstanceOf(_common.InternalServerErrorException);
+                expect(error.getResponse()).toEqual(expect.objectContaining({
+                    messageKey: 'system.service.not.available'
+                }));
+                expect(error.getResponse().message).toContain('boom during init');
+            }
+        });
+        it('does not cache a provider that failed to initialize', async ()=>{
+            _emailproviderregistry.EmailProviderRegistry.register('mailgun', FakeFailingInitProvider);
+            const config = {
+                provider: 'mailgun',
+                config: {}
+            };
+            await expect(service.createProvider(config)).rejects.toThrow();
+            // second attempt should also go through the (still failing) initialization path
+            await expect(service.createProvider(config)).rejects.toThrow();
+        });
+    });
+    describe('onModuleDestroy', ()=>{
+        it('closes every cached provider and clears the cache', async ()=>{
+            _emailproviderregistry.EmailProviderRegistry.register('smtp', FakeSuccessProvider);
+            const provider = await service.createProvider({
+                provider: 'smtp',
+                config: {}
+            });
+            await service.onModuleDestroy();
+            expect(provider.closeCalled).toBe(true);
+            // cache cleared -> a subsequent createProvider call re-initializes
+            _emailproviderregistry.EmailProviderRegistry.register('smtp', FakeSuccessProvider);
+            await service.createProvider({
+                provider: 'smtp',
+                config: {}
+            });
+            expect(FakeSuccessProvider.initializeCalls).toBe(2);
+        });
+        it('does not throw when a provider close() call rejects', async ()=>{
+            let FakeThrowingCloseProvider = class FakeThrowingCloseProvider extends FakeSuccessProvider {
+                async close() {
+                    throw new Error('close failed');
+                }
+            };
+            _emailproviderregistry.EmailProviderRegistry.register('smtp', FakeThrowingCloseProvider);
+            await service.createProvider({
+                provider: 'smtp',
+                config: {}
+            });
+            await expect(service.onModuleDestroy()).resolves.toBeUndefined();
+        });
+        it('is a no-op when nothing has been cached', async ()=>{
+            await expect(service.onModuleDestroy()).resolves.toBeUndefined();
+        });
+    });
+});

package/cjs/providers/email-provider.registry.spec.js

@@ -0,0 +1,58 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", {
+    value: true
+});
+const _emailproviderregistry = require("./email-provider.registry");
+let FakeProvider = class FakeProvider {
+    async sendEmail(_options) {
+        return {
+            success: true
+        };
+    }
+    async sendBulkEmails(_options) {
+        return [];
+    }
+    async healthCheck() {
+        return true;
+    }
+};
+describe('EmailProviderRegistry', ()=>{
+    afterEach(()=>{
+        _emailproviderregistry.EmailProviderRegistry.clear();
+    });
+    it('registers and retrieves a provider by exact name', ()=>{
+        _emailproviderregistry.EmailProviderRegistry.register('smtp', FakeProvider);
+        expect(_emailproviderregistry.EmailProviderRegistry.get('smtp')).toBe(FakeProvider);
+    });
+    it('normalizes provider names to lowercase on register and lookup', ()=>{
+        _emailproviderregistry.EmailProviderRegistry.register('SendGrid', FakeProvider);
+        expect(_emailproviderregistry.EmailProviderRegistry.get('sendgrid')).toBe(FakeProvider);
+        expect(_emailproviderregistry.EmailProviderRegistry.get('SENDGRID')).toBe(FakeProvider);
+        expect(_emailproviderregistry.EmailProviderRegistry.has('sendgrid')).toBe(true);
+    });
+    it('returns undefined for an unregistered provider', ()=>{
+        expect(_emailproviderregistry.EmailProviderRegistry.get('unknown-provider')).toBeUndefined();
+        expect(_emailproviderregistry.EmailProviderRegistry.has('unknown-provider')).toBe(false);
+    });
+    it('lists all registered provider names', ()=>{
+        _emailproviderregistry.EmailProviderRegistry.register('smtp', FakeProvider);
+        _emailproviderregistry.EmailProviderRegistry.register('mailgun', FakeProvider);
+        expect(_emailproviderregistry.EmailProviderRegistry.getAll().sort()).toEqual([
+            'mailgun',
+            'smtp'
+        ]);
+    });
+    it('clears all registered providers', ()=>{
+        _emailproviderregistry.EmailProviderRegistry.register('smtp', FakeProvider);
+        _emailproviderregistry.EmailProviderRegistry.clear();
+        expect(_emailproviderregistry.EmailProviderRegistry.getAll()).toEqual([]);
+        expect(_emailproviderregistry.EmailProviderRegistry.has('smtp')).toBe(false);
+    });
+    it('overwrites a previously registered provider for the same name', ()=>{
+        let OtherProvider = class OtherProvider extends FakeProvider {
+        };
+        _emailproviderregistry.EmailProviderRegistry.register('smtp', FakeProvider);
+        _emailproviderregistry.EmailProviderRegistry.register('smtp', OtherProvider);
+        expect(_emailproviderregistry.EmailProviderRegistry.get('smtp')).toBe(OtherProvider);
+    });
+});

package/cjs/providers/mailgun-provider.spec.js

@@ -0,0 +1,244 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", {
+    value: true
+});
+const _common = require("@nestjs/common");
+const _mailgunprovider = require("./mailgun-provider");
+// mailgun.js is not an installed dependency in this workspace, so the real dynamic
+// import() inside `initialize()` fails — that's exercised directly (no mocking needed).
+// For "happy path" behavior we bypass initialize() and inject a fake client, matching
+// the private `client`/`domain` fields the provider mutates internally.
+function injectClient(provider, client, domain = 'example.com') {
+    provider.client = client;
+    provider.domain = domain;
+}
+describe('MailgunProvider', ()=>{
+    let provider;
+    beforeEach(()=>{
+        provider = new _mailgunprovider.MailgunProvider();
+    });
+    describe('initialize', ()=>{
+        it('throws InternalServerErrorException with SDK_NOT_INSTALLED when mailgun.js is unavailable', async ()=>{
+            await expect(provider.initialize({
+                apiKey: 'key',
+                domain: 'example.com'
+            })).rejects.toThrow(_common.InternalServerErrorException);
+        });
+        it('surfaces the sdk name in the exception messageVariables', async ()=>{
+            try {
+                await provider.initialize({
+                    apiKey: 'key',
+                    domain: 'example.com'
+                });
+                fail('expected initialize to throw');
+            } catch (error) {
+                expect(error.getResponse()).toEqual(expect.objectContaining({
+                    messageKey: 'system.sdk.not.installed',
+                    messageVariables: {
+                        sdk: 'mailgun'
+                    }
+                }));
+            }
+        });
+    });
+    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: 'Mailgun provider not initialized'
+            });
+        });
+        it('sends via the mailgun client and returns the message id on success', async ()=>{
+            const create = jest.fn().mockResolvedValue({
+                id: '<msg-1@mailgun>'
+            });
+            injectClient(provider, {
+                messages: {
+                    create
+                }
+            });
+            const result = await provider.sendEmail({
+                to: 'a@example.com',
+                cc: [
+                    'b@example.com',
+                    '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@mailgun>'
+            });
+            expect(create).toHaveBeenCalledWith('example.com', expect.objectContaining({
+                from: 'Sender Name <sender@example.com>',
+                to: 'a@example.com',
+                subject: 'Hello',
+                html: '<p>hi</p>',
+                text: 'hi',
+                cc: 'b@example.com, c@example.com',
+                bcc: 'd@example.com',
+                'h:Reply-To': 'reply@example.com'
+            }));
+        });
+        it('omits optional fields (cc/bcc/replyTo/html/text) when not provided', async ()=>{
+            const create = jest.fn().mockResolvedValue({
+                id: 'id-1'
+            });
+            injectClient(provider, {
+                messages: {
+                    create
+                }
+            });
+            await provider.sendEmail({
+                to: 'a@example.com',
+                subject: 'Hi',
+                from: 'x@example.com'
+            });
+            const [, messageData] = create.mock.calls[0];
+            expect(messageData).not.toHaveProperty('cc');
+            expect(messageData).not.toHaveProperty('bcc');
+            expect(messageData).not.toHaveProperty('h:Reply-To');
+            expect(messageData).not.toHaveProperty('html');
+            expect(messageData).not.toHaveProperty('text');
+        });
+        it('base64-decodes attachment content before sending', async ()=>{
+            const create = jest.fn().mockResolvedValue({
+                id: 'id-1'
+            });
+            injectClient(provider, {
+                messages: {
+                    create
+                }
+            });
+            await provider.sendEmail({
+                to: 'a@example.com',
+                subject: 'Hi',
+                attachments: [
+                    {
+                        filename: 'doc.txt',
+                        content: Buffer.from('hello').toString('base64'),
+                        contentType: 'text/plain'
+                    }
+                ]
+            });
+            const [, messageData] = create.mock.calls[0];
+            const attachment = messageData.attachment[0];
+            expect(attachment.filename).toBe('doc.txt');
+            expect(attachment.contentType).toBe('text/plain');
+            expect(Buffer.isBuffer(attachment.data)).toBe(true);
+            expect(attachment.data.toString('utf8')).toBe('hello');
+        });
+        it('returns the error message when the mailgun client rejects with an Error', async ()=>{
+            injectClient(provider, {
+                messages: {
+                    create: jest.fn().mockRejectedValue(new Error('domain not found'))
+                }
+            });
+            const result = await provider.sendEmail({
+                to: 'a@example.com',
+                subject: 'Hi'
+            });
+            expect(result).toEqual({
+                success: false,
+                error: 'domain not found'
+            });
+        });
+        it('returns "Unknown error" when the mailgun client rejects with a non-Error', async ()=>{
+            injectClient(provider, {
+                messages: {
+                    create: jest.fn().mockRejectedValue('some string failure')
+                }
+            });
+            const result = await provider.sendEmail({
+                to: 'a@example.com',
+                subject: 'Hi'
+            });
+            expect(result).toEqual({
+                success: false,
+                error: 'Unknown error'
+            });
+        });
+    });
+    describe('sendBulkEmails', ()=>{
+        it('sends each message individually and aggregates the results', async ()=>{
+            const create = jest.fn().mockResolvedValueOnce({
+                id: 'id-1'
+            }).mockRejectedValueOnce(new Error('failed-2'));
+            injectClient(provider, {
+                messages: {
+                    create
+                }
+            });
+            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'
+                }
+            ]);
+            expect(create).toHaveBeenCalledTimes(2);
+        });
+    });
+    describe('healthCheck', ()=>{
+        it('returns false when not initialized', async ()=>{
+            await expect(provider.healthCheck()).resolves.toBe(false);
+        });
+        it('returns true when the mailgun domain lookup succeeds', async ()=>{
+            injectClient(provider, {
+                domains: {
+                    get: jest.fn().mockResolvedValue({})
+                }
+            });
+            await expect(provider.healthCheck()).resolves.toBe(true);
+        });
+        it('returns false when the mailgun domain lookup fails', async ()=>{
+            injectClient(provider, {
+                domains: {
+                    get: jest.fn().mockRejectedValue(new Error('nope'))
+                }
+            });
+            await expect(provider.healthCheck()).resolves.toBe(false);
+        });
+    });
+    describe('close', ()=>{
+        it('clears the client reference', async ()=>{
+            injectClient(provider, {
+                messages: {
+                    create: jest.fn()
+                }
+            });
+            await provider.close();
+            const result = await provider.sendEmail({
+                to: 'a@example.com',
+                subject: 'Hi'
+            });
+            expect(result).toEqual({
+                success: false,
+                error: 'Mailgun provider not initialized'
+            });
+        });
+    });
+});