@dereekb/nestjs 13.3.1 → 13.4.1

package/index.esm.js

@@ -1,4 +1,4 @@
-import { createParamDecorator, BadRequestException, InternalServerErrorException, Injectable, RequestMethod, Module, Logger, Inject } from '@nestjs/common';
+import { createParamDecorator, Logger, BadRequestException, InternalServerErrorException, Injectable, RequestMethod, Module, Inject } from '@nestjs/common';
 import rawbody from 'raw-body';
 import { parse } from 'querystring';
 import bodyParser from 'body-parser';
@@ -11,7 +11,14 @@ import { createDecipheriv, randomBytes, createCipheriv } from 'crypto';
  */ var IsRequestFromLocalHost = createParamDecorator(function(data, context) {
     return isLocalhost(context);
 });
-function isLocalhost(context) {
+/**
+ * Returns true if the request's origin header indicates the request came from localhost.
+ *
+ * Checks for both http://localhost and https://localhost origins.
+ *
+ * @param context - the NestJS execution context containing the HTTP request
+ * @returns true if the request origin is localhost
+ */ function isLocalhost(context) {
     var _req_headers_origin;
     var req = context.switchToHttp().getRequest();
     var origin = (_req_headers_origin = req.headers['origin']) !== null && _req_headers_origin !== void 0 ? _req_headers_origin : '';
@@ -158,7 +165,8 @@ function _ts_generator(thisArg, body) {
  * @Post('webhook')
  * handleWebhook(@ParseRawBody() body: RawBodyBuffer) { ... }
  * ```
- */ var ParseRawBody = createParamDecorator(function(_, context) {
+ */ var rawBodyLogger = new Logger('RawBody');
+var ParseRawBody = createParamDecorator(function(_, context) {
     return _async_to_generator(function() {
         var req, body;
         return _ts_generator(this, function(_state) {
@@ -166,7 +174,7 @@ function _ts_generator(thisArg, body) {
                 case 0:
                     req = context.switchToHttp().getRequest();
                     if (!req.readable) {
-                        console.error('RawBody request was not readable. This is generally due to bad configuration.');
+                        rawBodyLogger.error('RawBody request was not readable. This is generally due to bad configuration.');
                         throw new BadRequestException('Invalid body');
                     }
                     return [
@@ -202,7 +210,7 @@ function _ts_generator(thisArg, body) {
             req = context.switchToHttp().getRequest();
             body = req.body;
             if (!Buffer.isBuffer(body)) {
-                console.error('RawBody expected a buffer set to req.body.');
+                rawBodyLogger.error('RawBody expected a buffer set to req.body.');
                 throw new InternalServerErrorException('failed parsing body');
             }
             return [
@@ -554,9 +562,9 @@ function _type_of(obj) {
 /**
  * Merges two module metadata entries together.
  *
- * @param base
- * @param additional
- * @returns
+ * @param base - the base module metadata
+ * @param additional - additional metadata to merge in
+ * @returns the merged module metadata
  */ function mergeModuleMetadata(base) {
     var additional = arguments.length > 1 && arguments[1] !== void 0 ? arguments[1] : {};
     return {
@@ -578,7 +586,14 @@ function _type_of(obj) {
         ])
     };
 }
-function injectionTokensFromProviders(providers) {
+/**
+ * Extracts the injection tokens from an array (or single value) of NestJS Providers.
+ *
+ * For class providers, returns the class itself; for object providers, returns the provide token.
+ *
+ * @param providers - the providers to extract tokens from
+ * @returns an array of injection tokens
+ */ function injectionTokensFromProviders(providers) {
     return asArray(providers).map(function(x) {
         return (typeof x === "undefined" ? "undefined" : _type_of(x)) === 'object' ? x.provide : x;
     });
@@ -718,7 +733,14 @@ function _class_call_check$2(instance, Constructor) {
         throw new TypeError("Cannot call a class as a function");
     }
 }
-function clientAppConfigFactory(configService) {
+/**
+ * Factory that creates a ClientAppServiceConfig from environment variables.
+ *
+ * Reads the client web app URL from the CLIENT_WEB_APP_URL environment variable.
+ *
+ * @param configService - NestJS config service for reading environment variables
+ * @returns a validated ClientAppServiceConfig
+ */ function clientAppConfigFactory(configService) {
     var config = {
         client: {
             clientWebAppUrl: configService.get(CLIENT_WEB_APP_URL_ENV_VAR)
@@ -727,7 +749,11 @@ function clientAppConfigFactory(configService) {
     ClientAppServiceConfig.assertValidConfig(config);
     return config;
 }
-var ClientAppModule = function ClientAppModule() {
+/**
+ * NestJS module that provides the ClientAppService for accessing client application configuration.
+ *
+ * Reads the client web app URL from environment variables and makes it available via ClientAppService.
+ */ var ClientAppModule = function ClientAppModule() {
     _class_call_check$2(this, ClientAppModule);
 };
 ClientAppModule = __decorate([
@@ -742,7 +768,8 @@ ClientAppModule = __decorate([
                     ConfigService
                 ],
                 useFactory: clientAppConfigFactory
-            }
+            },
+            ClientAppService
         ],
         exports: [
             ClientAppService
@@ -770,7 +797,14 @@ function _class_call_check$1(instance, Constructor) {
 /**
  * Token to access a configured ServerEnvironmentServiceConfig for the app.
  */ var SERVER_ENV_TOKEN = 'SERVER_ENV_TOKEN';
-function serverEnvTokenProvider(env) {
+/**
+ * Creates a NestJS Provider that supplies a ServerEnvironmentConfig under the SERVER_ENV_TOKEN injection token.
+ *
+ * Use this to register a server environment configuration instance with the NestJS dependency injection container.
+ *
+ * @param env - the server environment config to provide
+ * @returns a NestJS Provider that supplies the config under SERVER_ENV_TOKEN
+ */ function serverEnvTokenProvider(env) {
     return {
         provide: SERVER_ENV_TOKEN,
         useValue: env
@@ -778,7 +812,9 @@ function serverEnvTokenProvider(env) {
 }
 
 /**
- * Checks process.env.NODE_ENV for "test"
+ * Checks process.env.NODE_ENV for "test".
+ *
+ * @returns true if the current Node environment is "test", false otherwise
  */ function isTestNodeEnv() {
     return process.env['NODE_ENV'] === 'test';
 }
@@ -869,6 +905,9 @@ var ENCRYPTED_FIELD_KEY_LENGTH = 32;
 /**
  * Validates that the given secret is a 64-character hexadecimal string (32 bytes for AES-256).
  *
+ * @param secret - the hex-encoded secret key string to validate
+ * @returns true if the secret is exactly 64 valid hex characters, false otherwise
+ *
  * @example
  * ```typescript
  * isValidAES256GCMEncryptionSecret('a'.repeat(64)); // true

package/mailgun/index.cjs.js

@@ -121,7 +121,8 @@ var MAILGUN_REPLY_TO_EMAIL_HEADER_DATA_VARIABLE_KEY = "h:Reply-To";
  *
  * @param config
  * @returns
- */ function convertMailgunTemplateEmailRequestToMailgunMessageData(config) {
+ */ // eslint-disable-next-line sonarjs/cognitive-complexity
+function convertMailgunTemplateEmailRequestToMailgunMessageData(config) {
     var _ref, _ref1, _ref2, _ref3, _request_finalizeRecipientVariables, _request_batchSend;
     var request = config.request, defaultSender = config.defaultSender, testEnvironment = config.isTestingEnvironment, tmp = config.recipientVariablePrefix, inputRecipientVariablePrefix = tmp === void 0 ? DEFAULT_RECIPIENT_VARIABLE_PREFIX : tmp, tmp1 = config.addRecipientVariablePrefixToAllMergedGlobalVariables, inputAddRecipientVariablePrefixToAllMergedGlobalVariables = tmp1 === void 0 ? true : tmp1, tmp2 = config.addCopyOfMergedRecipientVariablesWithoutPrefixToGlobalVariables, inputAddCopyOfMergedRecipientVariablesWithoutPrefixToGlobalVariables = tmp2 === void 0 ? false : tmp2, tmp3 = config.addCopyOfTemplateVariablesWithRecipientVariablePrefix, inputAddCopyOfTemplateVariablesWithRecipientVariablePrefix = tmp3 === void 0 ? false : tmp3;
     var recipientVariablesConfig = request.recipientVariablesConfig;
@@ -179,9 +180,9 @@ var MAILGUN_REPLY_TO_EMAIL_HEADER_DATA_VARIABLE_KEY = "h:Reply-To";
             }
         });
     }
-    var hasUserVariables = Boolean(data['recipient-variables']) || toInput.findIndex(function(x) {
+    var hasUserVariables = Boolean(data['recipient-variables']) || toInput.some(function(x) {
         return x.userVariables != null;
-    }) !== -1;
+    });
     if (hasUserVariables) {
         var _finalizeRecipientVariables;
         var recipientVariables = {};
@@ -199,7 +200,7 @@ var MAILGUN_REPLY_TO_EMAIL_HEADER_DATA_VARIABLE_KEY = "h:Reply-To";
                 forEach: function forEach(x) {
                     var _x = _sliced_to_array(x, 2), recipientEmail = _x[0], userVariables = _x[1];
                     var email = recipientEmail.toLowerCase();
-                    if (recipientVariables[email] != null) {
+                    if (email in recipientVariables) {
                         util.overrideInObject(recipientVariables[email], {
                             from: [
                                 userVariables
@@ -272,12 +273,26 @@ var MAILGUN_REPLY_TO_EMAIL_HEADER_DATA_VARIABLE_KEY = "h:Reply-To";
     }
     return data;
 }
-function convertMailgunRecipientsToStrings(recipients) {
+/**
+ * Converts an array of MailgunRecipient objects to formatted email address strings.
+ *
+ * Each recipient is formatted as "Name <email>" when a name is present, or just the email address.
+ *
+ * @param recipients - the recipients to convert
+ * @returns an array of formatted email address strings
+ */ function convertMailgunRecipientsToStrings(recipients) {
     return recipients.map(function(x) {
         return convertMailgunRecipientToString(x);
     });
 }
-function convertMailgunRecipientToString(recipient) {
+/**
+ * Converts a MailgunRecipient to a formatted email address string.
+ *
+ * Returns "Name <email>" when a name is present, or just the email address otherwise.
+ *
+ * @param recipient - the recipient to convert
+ * @returns a formatted email participant string
+ */ function convertMailgunRecipientToString(recipient) {
     var address = recipient.email;
     if (recipient.name) {
         address = "".concat(recipient.name, " <").concat(address, ">");
@@ -301,6 +316,10 @@ function convertMailgunRecipientToString(recipient) {
                 }
             }
             break;
+        case 'symbol':
+        case 'function':
+        case 'undefined':
+            break;
         case 'bigint':
         case 'boolean':
         case 'number':
@@ -309,7 +328,7 @@ function convertMailgunRecipientToString(recipient) {
             break;
         default:
             if (value) {
-                throw new Error('Invalid value "'.concat(value, '" passed to encodeMailgunTemplateVariableValue().'));
+                throw new Error('Invalid value "'.concat(String(value), '" passed to encodeMailgunTemplateVariableValue().'));
             }
     }
     return encodedValue;
@@ -398,8 +417,6 @@ var MailgunServiceConfig = /*#__PURE__*/ function() {
                     throw new Error('No client url specified.');
                 } else if (!config.sender) {
                     throw new Error('No mailgun sender specified.');
-                } else if (!config.messages) {
-                    throw new Error('No mailgun messages config specified.');
                 }
             }
         }
@@ -657,6 +674,7 @@ function _ts_generator(thisArg, body) {
 exports.MailgunService = /*#__PURE__*/ function() {
     function MailgunService(mailgunApi, serverEnvironmentService) {
         _class_call_check$1(this, MailgunService);
+        _define_property$1(this, "logger", new common.Logger('MailgunService'));
         _define_property$1(this, "_mailgunApi", void 0);
         _define_property$1(this, "_serverEnvironmentService", void 0);
         this._mailgunApi = mailgunApi;
@@ -679,7 +697,7 @@ exports.MailgunService = /*#__PURE__*/ function() {
             key: "sendTemplateEmail",
             value: function sendTemplateEmail(request) {
                 return _async_to_generator(function() {
-                    var domain, sender, isTestingEnvironment, recipientVariablePrefix, data, result, shouldSend, e;
+                    var _request_sendTestEmails, domain, sender, isTestingEnvironment, recipientVariablePrefix, data, result, shouldSend, e;
                     return _ts_generator(this, function(_state) {
                         switch(_state.label){
                             case 0:
@@ -693,7 +711,7 @@ exports.MailgunService = /*#__PURE__*/ function() {
                                     recipientVariablePrefix: recipientVariablePrefix,
                                     isTestingEnvironment: isTestingEnvironment
                                 });
-                                shouldSend = !isTestingEnvironment || request.sendTestEmails || this.mailgunApi.config.messages.sendTestEmails;
+                                shouldSend = !isTestingEnvironment || ((_request_sendTestEmails = request.sendTestEmails) !== null && _request_sendTestEmails !== void 0 ? _request_sendTestEmails : this.mailgunApi.config.messages.sendTestEmails);
                                 if (!shouldSend) return [
                                     3,
                                     5
@@ -718,7 +736,7 @@ exports.MailgunService = /*#__PURE__*/ function() {
                                 ];
                             case 3:
                                 e = _state.sent();
-                                console.error('Failed sending email: ', e);
+                                this.logger.error('Failed sending email: ', e);
                                 throw e;
                             case 4:
                                 return [
@@ -755,7 +773,16 @@ function _class_call_check(instance, Constructor) {
         throw new TypeError("Cannot call a class as a function");
     }
 }
-function mailgunServiceConfigFactory(configService, serverEnvironmentService) {
+var mailgunLogger = new common.Logger('MailgunServiceModule');
+/**
+ * Factory that creates a MailgunServiceConfig from environment variables.
+ *
+ * Automatically switches to sandbox credentials when USE_MAILGUN_SANDBOX is true or the environment is a test environment.
+ *
+ * @param configService - NestJS config service for reading environment variables
+ * @param serverEnvironmentService - service indicating the current server environment
+ * @returns a validated MailgunServiceConfig
+ */ function mailgunServiceConfigFactory(configService, serverEnvironmentService) {
     var _configService_get, _configService_get1, _configService_get2;
     var isTestingEnv = serverEnvironmentService.isTestingEnv;
     var useSandbox = configService.get('USE_MAILGUN_SANDBOX') === 'true' || isTestingEnv;
@@ -768,10 +795,10 @@ function mailgunServiceConfigFactory(configService, serverEnvironmentService) {
         if (!key || !domain) {
             throw new Error('USE_MAILGUN_SANDBOX is set to "true" (or current environment is a testing environment), but no environment variables for the sandbox (MAILGUN_SANDBOX_API_KEY, MAILGUN_SANDBOX_DOMAIN) are provided.');
         } else if (!serverEnvironmentService.isTestingEnv) {
-            console.log('Using Mailgun Sandbox Domain: ', domain);
+            mailgunLogger.log("Using Mailgun Sandbox Domain: ".concat(domain));
         }
-    } else if (!serverEnvironmentService.isTestingEnv) {
-        console.log('Using Mailgun Production Domain: ', domain);
+    } else {
+        mailgunLogger.log("Using Mailgun Production Domain: ".concat(domain));
     }
     var name = configService.get('MAILGUN_SENDER_NAME');
     var email = configService.get('MAILGUN_SENDER_EMAIL');
@@ -805,7 +832,12 @@ function mailgunServiceConfigFactory(configService, serverEnvironmentService) {
     MailgunServiceConfig.assertValidConfig(config);
     return config;
 }
-exports.MailgunServiceModule = function MailgunServiceModule() {
+/**
+ * NestJS module that provides the MailgunApi and MailgunService for sending emails.
+ *
+ * Reads Mailgun credentials and sender configuration from environment variables,
+ * with automatic fallback to sandbox settings in test environments.
+ */ exports.MailgunServiceModule = function MailgunServiceModule() {
     _class_call_check(this, MailgunServiceModule);
 };
 exports.MailgunServiceModule = __decorate([
@@ -911,6 +943,9 @@ function _unsupported_iterable_to_array(o, minLen) {
  */ var MAILGUN_BATCH_SEND_RECIPIENT_SUBJECT_TEMPLATE = "%recipient.subject%";
 /**
  * Creates a composite key from the from/replyTo email addresses used to group MailgunRecipientBatchSendTarget values.
+ *
+ * @param recipient - the batch send target whose from/replyTo addresses are used as the grouping key
+ * @returns a string key in the form "f:{fromEmail}|r:{replyToEmail}" used to group recipients into batches
  */ function mailgunRecipientBatchSendTargetFromReplyToBatchGroupKey(recipient) {
     var _ref, _ref1;
     var _recipient_from, _recipient_replyTo;
@@ -978,21 +1013,13 @@ function _unsupported_iterable_to_array(o, minLen) {
             var replyTo = recipient.replyTo;
             if (mailgunRecipientBatchSendTargetEntityKeyRecipientLookup) {
                 // try the fromKey, otherwise use the baseRequest.from
-                if (!from) {
-                    from = mailgunRecipientBatchSendTargetEntityKeyRecipientLookup.getRecipientOrDefaultForKey(recipient.fromKey, baseRequest.from);
-                }
+                from !== null && from !== void 0 ? from : from = mailgunRecipientBatchSendTargetEntityKeyRecipientLookup.getRecipientOrDefaultForKey(recipient.fromKey, baseRequest.from);
                 // try the replyToKey, otherwise use the baseRequest.replyTo
-                if (!replyTo) {
-                    replyTo = mailgunRecipientBatchSendTargetEntityKeyRecipientLookup.getRecipientOrDefaultForKey(recipient.replyToKey, baseRequest.replyTo);
-                }
+                replyTo !== null && replyTo !== void 0 ? replyTo : replyTo = mailgunRecipientBatchSendTargetEntityKeyRecipientLookup.getRecipientOrDefaultForKey(recipient.replyToKey, baseRequest.replyTo);
             } else {
                 // use defaults from base request
-                if (!from) {
-                    from = baseRequest.from;
-                }
-                if (!replyTo) {
-                    replyTo = baseRequest.replyTo;
-                }
+                from !== null && from !== void 0 ? from : from = baseRequest.from;
+                replyTo !== null && replyTo !== void 0 ? replyTo : replyTo = baseRequest.replyTo;
             }
             var cc = determineCarbonCopyRecipients({
                 baseRequestCarbonCopyRecipients: baseRequestCc,
@@ -1012,11 +1039,12 @@ function _unsupported_iterable_to_array(o, minLen) {
             });
             return result;
         });
-        var allowBatchSend = configAllowBatchSend && (allowSingleRecipientBatchSendRequests || recipients.length > 1);
+        var allowBatchSend = configAllowBatchSend && (allowSingleRecipientBatchSendRequests !== null && allowSingleRecipientBatchSendRequests !== void 0 ? allowSingleRecipientBatchSendRequests : recipients.length > 1);
         var nonBatchSendRequests = [];
         var batchSendRequestRecipients = [];
         recipients.forEach(function(recipient) {
             var _recipient_cc, _recipient_bcc;
+            // eslint-disable-next-line @typescript-eslint/prefer-nullish-coalescing -- intentional: need || so empty cc array (length 0) falls through to check bcc
             var recipientHasCarbonCopy = Boolean(((_recipient_cc = recipient.cc) === null || _recipient_cc === void 0 ? void 0 : _recipient_cc.length) || ((_recipient_bcc = recipient.bcc) === null || _recipient_bcc === void 0 ? void 0 : _recipient_bcc.length));
             if (allowBatchSend && !recipientHasCarbonCopy) {
                 // add to batch send recipients

package/mailgun/index.esm.js

@@ -1,6 +1,6 @@
 import { isTestNodeEnv, ServerEnvironmentService } from '@dereekb/nestjs';
 import { MAP_IDENTITY, asArray, forEachKeyValue, objectIsEmpty, addToSet, overrideInObject, KeyValueTypleValueFilter, forEachInIterable, makeValuesGroupMap, filterMaybeArrayValues } from '@dereekb/util';
-import { Injectable, Inject, Module } from '@nestjs/common';
+import { Injectable, Inject, Logger, Module } from '@nestjs/common';
 import Mailgun from 'mailgun.js';
 import FormData from 'form-data';
 import { ConfigService, ConfigModule } from '@nestjs/config';
@@ -119,7 +119,8 @@ var MAILGUN_REPLY_TO_EMAIL_HEADER_DATA_VARIABLE_KEY = "h:Reply-To";
  *
  * @param config
  * @returns
- */ function convertMailgunTemplateEmailRequestToMailgunMessageData(config) {
+ */ // eslint-disable-next-line sonarjs/cognitive-complexity
+function convertMailgunTemplateEmailRequestToMailgunMessageData(config) {
     var _ref, _ref1, _ref2, _ref3, _request_finalizeRecipientVariables, _request_batchSend;
     var request = config.request, defaultSender = config.defaultSender, testEnvironment = config.isTestingEnvironment, tmp = config.recipientVariablePrefix, inputRecipientVariablePrefix = tmp === void 0 ? DEFAULT_RECIPIENT_VARIABLE_PREFIX : tmp, tmp1 = config.addRecipientVariablePrefixToAllMergedGlobalVariables, inputAddRecipientVariablePrefixToAllMergedGlobalVariables = tmp1 === void 0 ? true : tmp1, tmp2 = config.addCopyOfMergedRecipientVariablesWithoutPrefixToGlobalVariables, inputAddCopyOfMergedRecipientVariablesWithoutPrefixToGlobalVariables = tmp2 === void 0 ? false : tmp2, tmp3 = config.addCopyOfTemplateVariablesWithRecipientVariablePrefix, inputAddCopyOfTemplateVariablesWithRecipientVariablePrefix = tmp3 === void 0 ? false : tmp3;
     var recipientVariablesConfig = request.recipientVariablesConfig;
@@ -177,9 +178,9 @@ var MAILGUN_REPLY_TO_EMAIL_HEADER_DATA_VARIABLE_KEY = "h:Reply-To";
             }
         });
     }
-    var hasUserVariables = Boolean(data['recipient-variables']) || toInput.findIndex(function(x) {
+    var hasUserVariables = Boolean(data['recipient-variables']) || toInput.some(function(x) {
         return x.userVariables != null;
-    }) !== -1;
+    });
     if (hasUserVariables) {
         var _finalizeRecipientVariables;
         var recipientVariables = {};
@@ -197,7 +198,7 @@ var MAILGUN_REPLY_TO_EMAIL_HEADER_DATA_VARIABLE_KEY = "h:Reply-To";
                 forEach: function forEach(x) {
                     var _x = _sliced_to_array(x, 2), recipientEmail = _x[0], userVariables = _x[1];
                     var email = recipientEmail.toLowerCase();
-                    if (recipientVariables[email] != null) {
+                    if (email in recipientVariables) {
                         overrideInObject(recipientVariables[email], {
                             from: [
                                 userVariables
@@ -270,12 +271,26 @@ var MAILGUN_REPLY_TO_EMAIL_HEADER_DATA_VARIABLE_KEY = "h:Reply-To";
     }
     return data;
 }
-function convertMailgunRecipientsToStrings(recipients) {
+/**
+ * Converts an array of MailgunRecipient objects to formatted email address strings.
+ *
+ * Each recipient is formatted as "Name <email>" when a name is present, or just the email address.
+ *
+ * @param recipients - the recipients to convert
+ * @returns an array of formatted email address strings
+ */ function convertMailgunRecipientsToStrings(recipients) {
     return recipients.map(function(x) {
         return convertMailgunRecipientToString(x);
     });
 }
-function convertMailgunRecipientToString(recipient) {
+/**
+ * Converts a MailgunRecipient to a formatted email address string.
+ *
+ * Returns "Name <email>" when a name is present, or just the email address otherwise.
+ *
+ * @param recipient - the recipient to convert
+ * @returns a formatted email participant string
+ */ function convertMailgunRecipientToString(recipient) {
     var address = recipient.email;
     if (recipient.name) {
         address = "".concat(recipient.name, " <").concat(address, ">");
@@ -299,6 +314,10 @@ function convertMailgunRecipientToString(recipient) {
                 }
             }
             break;
+        case 'symbol':
+        case 'function':
+        case 'undefined':
+            break;
         case 'bigint':
         case 'boolean':
         case 'number':
@@ -307,7 +326,7 @@ function convertMailgunRecipientToString(recipient) {
             break;
         default:
             if (value) {
-                throw new Error('Invalid value "'.concat(value, '" passed to encodeMailgunTemplateVariableValue().'));
+                throw new Error('Invalid value "'.concat(String(value), '" passed to encodeMailgunTemplateVariableValue().'));
             }
     }
     return encodedValue;
@@ -396,8 +415,6 @@ var MailgunServiceConfig = /*#__PURE__*/ function() {
                     throw new Error('No client url specified.');
                 } else if (!config.sender) {
                     throw new Error('No mailgun sender specified.');
-                } else if (!config.messages) {
-                    throw new Error('No mailgun messages config specified.');
                 }
             }
         }
@@ -655,6 +672,7 @@ function _ts_generator(thisArg, body) {
 var MailgunService = /*#__PURE__*/ function() {
     function MailgunService(mailgunApi, serverEnvironmentService) {
         _class_call_check$1(this, MailgunService);
+        _define_property$1(this, "logger", new Logger('MailgunService'));
         _define_property$1(this, "_mailgunApi", void 0);
         _define_property$1(this, "_serverEnvironmentService", void 0);
         this._mailgunApi = mailgunApi;
@@ -677,7 +695,7 @@ var MailgunService = /*#__PURE__*/ function() {
             key: "sendTemplateEmail",
             value: function sendTemplateEmail(request) {
                 return _async_to_generator(function() {
-                    var domain, sender, isTestingEnvironment, recipientVariablePrefix, data, result, shouldSend, e;
+                    var _request_sendTestEmails, domain, sender, isTestingEnvironment, recipientVariablePrefix, data, result, shouldSend, e;
                     return _ts_generator(this, function(_state) {
                         switch(_state.label){
                             case 0:
@@ -691,7 +709,7 @@ var MailgunService = /*#__PURE__*/ function() {
                                     recipientVariablePrefix: recipientVariablePrefix,
                                     isTestingEnvironment: isTestingEnvironment
                                 });
-                                shouldSend = !isTestingEnvironment || request.sendTestEmails || this.mailgunApi.config.messages.sendTestEmails;
+                                shouldSend = !isTestingEnvironment || ((_request_sendTestEmails = request.sendTestEmails) !== null && _request_sendTestEmails !== void 0 ? _request_sendTestEmails : this.mailgunApi.config.messages.sendTestEmails);
                                 if (!shouldSend) return [
                                     3,
                                     5
@@ -716,7 +734,7 @@ var MailgunService = /*#__PURE__*/ function() {
                                 ];
                             case 3:
                                 e = _state.sent();
-                                console.error('Failed sending email: ', e);
+                                this.logger.error('Failed sending email: ', e);
                                 throw e;
                             case 4:
                                 return [
@@ -753,7 +771,16 @@ function _class_call_check(instance, Constructor) {
         throw new TypeError("Cannot call a class as a function");
     }
 }
-function mailgunServiceConfigFactory(configService, serverEnvironmentService) {
+var mailgunLogger = new Logger('MailgunServiceModule');
+/**
+ * Factory that creates a MailgunServiceConfig from environment variables.
+ *
+ * Automatically switches to sandbox credentials when USE_MAILGUN_SANDBOX is true or the environment is a test environment.
+ *
+ * @param configService - NestJS config service for reading environment variables
+ * @param serverEnvironmentService - service indicating the current server environment
+ * @returns a validated MailgunServiceConfig
+ */ function mailgunServiceConfigFactory(configService, serverEnvironmentService) {
     var _configService_get, _configService_get1, _configService_get2;
     var isTestingEnv = serverEnvironmentService.isTestingEnv;
     var useSandbox = configService.get('USE_MAILGUN_SANDBOX') === 'true' || isTestingEnv;
@@ -766,10 +793,10 @@ function mailgunServiceConfigFactory(configService, serverEnvironmentService) {
         if (!key || !domain) {
             throw new Error('USE_MAILGUN_SANDBOX is set to "true" (or current environment is a testing environment), but no environment variables for the sandbox (MAILGUN_SANDBOX_API_KEY, MAILGUN_SANDBOX_DOMAIN) are provided.');
         } else if (!serverEnvironmentService.isTestingEnv) {
-            console.log('Using Mailgun Sandbox Domain: ', domain);
+            mailgunLogger.log("Using Mailgun Sandbox Domain: ".concat(domain));
         }
-    } else if (!serverEnvironmentService.isTestingEnv) {
-        console.log('Using Mailgun Production Domain: ', domain);
+    } else {
+        mailgunLogger.log("Using Mailgun Production Domain: ".concat(domain));
     }
     var name = configService.get('MAILGUN_SENDER_NAME');
     var email = configService.get('MAILGUN_SENDER_EMAIL');
@@ -803,7 +830,12 @@ function mailgunServiceConfigFactory(configService, serverEnvironmentService) {
     MailgunServiceConfig.assertValidConfig(config);
     return config;
 }
-var MailgunServiceModule = function MailgunServiceModule() {
+/**
+ * NestJS module that provides the MailgunApi and MailgunService for sending emails.
+ *
+ * Reads Mailgun credentials and sender configuration from environment variables,
+ * with automatic fallback to sandbox settings in test environments.
+ */ var MailgunServiceModule = function MailgunServiceModule() {
     _class_call_check(this, MailgunServiceModule);
 };
 MailgunServiceModule = __decorate([
@@ -909,6 +941,9 @@ function _unsupported_iterable_to_array(o, minLen) {
  */ var MAILGUN_BATCH_SEND_RECIPIENT_SUBJECT_TEMPLATE = "%recipient.subject%";
 /**
  * Creates a composite key from the from/replyTo email addresses used to group MailgunRecipientBatchSendTarget values.
+ *
+ * @param recipient - the batch send target whose from/replyTo addresses are used as the grouping key
+ * @returns a string key in the form "f:{fromEmail}|r:{replyToEmail}" used to group recipients into batches
  */ function mailgunRecipientBatchSendTargetFromReplyToBatchGroupKey(recipient) {
     var _ref, _ref1;
     var _recipient_from, _recipient_replyTo;
@@ -976,21 +1011,13 @@ function _unsupported_iterable_to_array(o, minLen) {
             var replyTo = recipient.replyTo;
             if (mailgunRecipientBatchSendTargetEntityKeyRecipientLookup) {
                 // try the fromKey, otherwise use the baseRequest.from
-                if (!from) {
-                    from = mailgunRecipientBatchSendTargetEntityKeyRecipientLookup.getRecipientOrDefaultForKey(recipient.fromKey, baseRequest.from);
-                }
+                from !== null && from !== void 0 ? from : from = mailgunRecipientBatchSendTargetEntityKeyRecipientLookup.getRecipientOrDefaultForKey(recipient.fromKey, baseRequest.from);
                 // try the replyToKey, otherwise use the baseRequest.replyTo
-                if (!replyTo) {
-                    replyTo = mailgunRecipientBatchSendTargetEntityKeyRecipientLookup.getRecipientOrDefaultForKey(recipient.replyToKey, baseRequest.replyTo);
-                }
+                replyTo !== null && replyTo !== void 0 ? replyTo : replyTo = mailgunRecipientBatchSendTargetEntityKeyRecipientLookup.getRecipientOrDefaultForKey(recipient.replyToKey, baseRequest.replyTo);
             } else {
                 // use defaults from base request
-                if (!from) {
-                    from = baseRequest.from;
-                }
-                if (!replyTo) {
-                    replyTo = baseRequest.replyTo;
-                }
+                from !== null && from !== void 0 ? from : from = baseRequest.from;
+                replyTo !== null && replyTo !== void 0 ? replyTo : replyTo = baseRequest.replyTo;
             }
             var cc = determineCarbonCopyRecipients({
                 baseRequestCarbonCopyRecipients: baseRequestCc,
@@ -1010,11 +1037,12 @@ function _unsupported_iterable_to_array(o, minLen) {
             });
             return result;
         });
-        var allowBatchSend = configAllowBatchSend && (allowSingleRecipientBatchSendRequests || recipients.length > 1);
+        var allowBatchSend = configAllowBatchSend && (allowSingleRecipientBatchSendRequests !== null && allowSingleRecipientBatchSendRequests !== void 0 ? allowSingleRecipientBatchSendRequests : recipients.length > 1);
         var nonBatchSendRequests = [];
         var batchSendRequestRecipients = [];
         recipients.forEach(function(recipient) {
             var _recipient_cc, _recipient_bcc;
+            // eslint-disable-next-line @typescript-eslint/prefer-nullish-coalescing -- intentional: need || so empty cc array (length 0) falls through to check bcc
             var recipientHasCarbonCopy = Boolean(((_recipient_cc = recipient.cc) === null || _recipient_cc === void 0 ? void 0 : _recipient_cc.length) || ((_recipient_bcc = recipient.bcc) === null || _recipient_bcc === void 0 ? void 0 : _recipient_bcc.length));
             if (allowBatchSend && !recipientHasCarbonCopy) {
                 // add to batch send recipients

package/mailgun/package.json

@@ -1,12 +1,12 @@
 {
   "name": "@dereekb/nestjs/mailgun",
-  "version": "13.3.1",
+  "version": "13.4.1",
   "peerDependencies": {
-    "@dereekb/date": "13.3.1",
-    "@dereekb/model": "13.3.1",
-    "@dereekb/nestjs": "13.3.1",
-    "@dereekb/rxjs": "13.3.1",
-    "@dereekb/util": "13.3.1",
+    "@dereekb/date": "13.4.1",
+    "@dereekb/model": "13.4.1",
+    "@dereekb/nestjs": "13.4.1",
+    "@dereekb/rxjs": "13.4.1",
+    "@dereekb/util": "13.4.1",
     "@nestjs/common": "^11.1.16",
     "@nestjs/config": "^4.0.3",
     "form-data": "^4.0.0",

package/mailgun/src/lib/mailgun.api.d.ts

@@ -1,11 +1,13 @@
+import { type EmailParticipantString, type WebsiteUrl } from '@dereekb/util';
 import { MailgunServiceConfig } from './mailgun.config';
+import { type MailgunSenderDomainString } from './mailgun';
 import { type MailgunClient, type MailgunMessagesClient } from './mailgun.type';
 export declare class MailgunApi {
     readonly config: MailgunServiceConfig;
     readonly client: MailgunClient;
     constructor(config: MailgunServiceConfig);
     get messages(): MailgunMessagesClient;
-    get clientUrl(): string;
-    get domain(): string;
-    get sender(): string;
+    get clientUrl(): WebsiteUrl;
+    get domain(): MailgunSenderDomainString;
+    get sender(): EmailParticipantString;
 }