@flusys/nestjs-email 6.0.2 → 6.1.1

package/fesm/entities/index.spec.js

@@ -0,0 +1,14 @@
+import { getEmailEntitiesByConfig, EmailCoreEntities, EmailCompanyEntities } from './index';
+describe('getEmailEntitiesByConfig', ()=>{
+    it('returns the core entities when the company feature is disabled', ()=>{
+        expect(getEmailEntitiesByConfig(false)).toBe(EmailCoreEntities);
+    });
+    it('returns the company-scoped entities when the company feature is enabled', ()=>{
+        expect(getEmailEntitiesByConfig(true)).toBe(EmailCompanyEntities);
+    });
+    it('core and company entity sets are disjoint (never mixed)', ()=>{
+        const core = getEmailEntitiesByConfig(false);
+        const company = getEmailEntitiesByConfig(true);
+        expect(core.some((e)=>company.includes(e))).toBe(false);
+    });
+});

package/fesm/modules/email.module.spec.js

@@ -0,0 +1,138 @@
+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;
+}
+import { EmailModule } from './email.module';
+import { EMAIL_MODULE_OPTIONS } from '../config/email.constants';
+import { EmailConfigController, EmailSendController, EmailTemplateController } from '../controllers';
+function providerTokens(providers) {
+    return providers.map((p)=>typeof p === 'function' ? p : p.provide);
+}
+describe('EmailModule', ()=>{
+    describe('forRoot', ()=>{
+        it('should default to a non-global module with all controllers registered', ()=>{
+            const dynamicModule = EmailModule.forRoot({});
+            expect(dynamicModule.module).toBe(EmailModule);
+            expect(dynamicModule.global).toBe(false);
+            expect(dynamicModule.controllers).toEqual([
+                EmailConfigController,
+                EmailTemplateController,
+                EmailSendController
+            ]);
+        });
+        it('should respect global: true', ()=>{
+            expect(EmailModule.forRoot({
+                global: true
+            }).global).toBe(true);
+        });
+        it('should register no controllers when includeController is false', ()=>{
+            expect(EmailModule.forRoot({
+                includeController: false
+            }).controllers).toEqual([]);
+        });
+        it('should register a EMAIL_MODULE_OPTIONS provider carrying the given options', ()=>{
+            const options = {
+                bootstrapAppConfig: {
+                    enableCompanyFeature: true
+                }
+            };
+            const dynamicModule = EmailModule.forRoot(options);
+            const provider = dynamicModule.providers.find((p)=>p.provide === EMAIL_MODULE_OPTIONS);
+            expect(provider.useValue).toBe(options);
+        });
+        it('should always export the same fixed set of services', ()=>{
+            expect(EmailModule.forRoot({}).exports).toHaveLength(6);
+        });
+    });
+    describe('forRootAsync', ()=>{
+        it('should forward external imports alongside CacheModule/UtilsModule', ()=>{
+            let FakeImportedModule = class FakeImportedModule {
+            };
+            const dynamicModule = EmailModule.forRootAsync({
+                bootstrapAppConfig: {},
+                imports: [
+                    FakeImportedModule
+                ]
+            });
+            expect(dynamicModule.imports).toEqual(expect.arrayContaining([
+                FakeImportedModule
+            ]));
+        });
+        it('useFactory: builds an EMAIL_MODULE_OPTIONS provider that merges resolved config into the static options', async ()=>{
+            const useFactory = jest.fn().mockResolvedValue({
+                defaultFrom: 'noreply@flusys.io'
+            });
+            const dynamicModule = EmailModule.forRootAsync({
+                bootstrapAppConfig: {},
+                useFactory,
+                inject: [
+                    'SOME_TOKEN'
+                ]
+            });
+            const provider = dynamicModule.providers.find((p)=>p.provide === EMAIL_MODULE_OPTIONS);
+            expect(provider.inject).toEqual([
+                'SOME_TOKEN'
+            ]);
+            const resolved = await provider.useFactory('injected');
+            expect(useFactory).toHaveBeenCalledWith('injected');
+            expect(resolved.config).toEqual({
+                defaultFrom: 'noreply@flusys.io'
+            });
+        });
+        it('useClass: registers both the class provider and an options provider calling createEmailOptions()', async ()=>{
+            let MyOptionsFactory = class MyOptionsFactory {
+                constructor(){
+                    _define_property(this, "createEmailOptions", jest.fn().mockResolvedValue({
+                        defaultFrom: 'from-class@flusys.io'
+                    }));
+                }
+            };
+            const dynamicModule = EmailModule.forRootAsync({
+                bootstrapAppConfig: {},
+                useClass: MyOptionsFactory
+            });
+            const classProvider = dynamicModule.providers.find((p)=>p.provide === MyOptionsFactory);
+            expect(classProvider.useClass).toBe(MyOptionsFactory);
+            const optionsProvider = dynamicModule.providers.find((p)=>p.provide === EMAIL_MODULE_OPTIONS);
+            const instance = new MyOptionsFactory();
+            const resolved = await optionsProvider.useFactory(instance);
+            expect(instance.createEmailOptions).toHaveBeenCalled();
+            expect(resolved.config).toEqual({
+                defaultFrom: 'from-class@flusys.io'
+            });
+        });
+        it('useExisting: registers a single options provider without a duplicate class registration', async ()=>{
+            let MyOptionsFactory = class MyOptionsFactory {
+                constructor(){
+                    _define_property(this, "createEmailOptions", jest.fn().mockResolvedValue({
+                        defaultFrom: 'from-existing@flusys.io'
+                    }));
+                }
+            };
+            const dynamicModule = EmailModule.forRootAsync({
+                bootstrapAppConfig: {},
+                useExisting: MyOptionsFactory
+            });
+            expect(dynamicModule.providers.filter((p)=>p.provide === MyOptionsFactory)).toHaveLength(0);
+            const optionsProvider = dynamicModule.providers.find((p)=>p.provide === EMAIL_MODULE_OPTIONS);
+            expect(optionsProvider.inject).toEqual([
+                MyOptionsFactory
+            ]);
+        });
+        it('should register no EMAIL_MODULE_OPTIONS provider when neither useFactory, useClass, nor useExisting is given', ()=>{
+            const dynamicModule = EmailModule.forRootAsync({
+                bootstrapAppConfig: {}
+            });
+            expect(providerTokens(dynamicModule.providers)).not.toContain(EMAIL_MODULE_OPTIONS);
+        });
+    });
+});

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

@@ -0,0 +1,238 @@
+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;
+}
+import { InternalServerErrorException, NotFoundException } from '@nestjs/common';
+import { EmailFactoryService } from './email-factory.service';
+import { EmailProviderRegistry } from './email-provider.registry';
+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();
+        EmailProviderRegistry.clear();
+        FakeSuccessProvider.initializeCalls = 0;
+        FakeSuccessProvider.instances = [];
+    });
+    afterEach(()=>{
+        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(NotFoundException);
+        });
+        it('throws NotFoundException with the config-not-found messageKey and available list', async ()=>{
+            EmailProviderRegistry.register('smtp', FakeSuccessProvider);
+            const config = {
+                provider: 'unknown',
+                config: {}
+            };
+            try {
+                await service.createProvider(config);
+                fail('expected createProvider to throw');
+            } catch (error) {
+                expect(error).toBeInstanceOf(NotFoundException);
+                expect(error.getResponse()).toEqual(expect.objectContaining({
+                    messageKey: 'email.send.config.not.found'
+                }));
+            }
+        });
+        it('instantiates and initializes the provider on cache miss', async ()=>{
+            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.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.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.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.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.register('mailgun', FakeFailingInitProvider);
+            const config = {
+                provider: 'mailgun',
+                config: {}
+            };
+            try {
+                await service.createProvider(config);
+                fail('expected createProvider to throw');
+            } catch (error) {
+                expect(error).toBeInstanceOf(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.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.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.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.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/fesm/providers/email-provider.registry.spec.js

@@ -0,0 +1,54 @@
+import { EmailProviderRegistry } from './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.clear();
+    });
+    it('registers and retrieves a provider by exact name', ()=>{
+        EmailProviderRegistry.register('smtp', FakeProvider);
+        expect(EmailProviderRegistry.get('smtp')).toBe(FakeProvider);
+    });
+    it('normalizes provider names to lowercase on register and lookup', ()=>{
+        EmailProviderRegistry.register('SendGrid', FakeProvider);
+        expect(EmailProviderRegistry.get('sendgrid')).toBe(FakeProvider);
+        expect(EmailProviderRegistry.get('SENDGRID')).toBe(FakeProvider);
+        expect(EmailProviderRegistry.has('sendgrid')).toBe(true);
+    });
+    it('returns undefined for an unregistered provider', ()=>{
+        expect(EmailProviderRegistry.get('unknown-provider')).toBeUndefined();
+        expect(EmailProviderRegistry.has('unknown-provider')).toBe(false);
+    });
+    it('lists all registered provider names', ()=>{
+        EmailProviderRegistry.register('smtp', FakeProvider);
+        EmailProviderRegistry.register('mailgun', FakeProvider);
+        expect(EmailProviderRegistry.getAll().sort()).toEqual([
+            'mailgun',
+            'smtp'
+        ]);
+    });
+    it('clears all registered providers', ()=>{
+        EmailProviderRegistry.register('smtp', FakeProvider);
+        EmailProviderRegistry.clear();
+        expect(EmailProviderRegistry.getAll()).toEqual([]);
+        expect(EmailProviderRegistry.has('smtp')).toBe(false);
+    });
+    it('overwrites a previously registered provider for the same name', ()=>{
+        let OtherProvider = class OtherProvider extends FakeProvider {
+        };
+        EmailProviderRegistry.register('smtp', FakeProvider);
+        EmailProviderRegistry.register('smtp', OtherProvider);
+        expect(EmailProviderRegistry.get('smtp')).toBe(OtherProvider);
+    });
+});

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

@@ -0,0 +1,240 @@
+import { InternalServerErrorException } from '@nestjs/common';
+import { MailgunProvider } from './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();
+    });
+    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(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'
+            });
+        });
+    });
+});