@dereekb/nestjs 13.41.0 → 13.42.0

package/eslint/package.json

@@ -1,9 +1,9 @@
 {
   "name": "@dereekb/nestjs/eslint",
-  "version": "13.41.0",
+  "version": "13.42.0",
   "type": "module",
   "peerDependencies": {
-    "@dereekb/util": "13.41.0",
+    "@dereekb/util": "13.42.0",
     "@typescript-eslint/utils": "8.59.3"
   },
   "devDependencies": {

package/mailgun/index.esm.js

@@ -1602,14 +1602,69 @@ function _unsupported_iterable_to_array(o, minLen) {
  *
  * @param config - Factory configuration providing the base request, recipient lookup, and per-recipient variable handling.
  * @returns A factory that expands `MailgunRecipientBatchSendTarget` lists into individual `MailgunTemplateEmailRequest` objects.
- * @throws {Error} When no subject is configured and `useSubjectFromRecipientUserVariables` is false.
+ * @throws {Error} When no subject is configured and `useSubjectFromRecipientUserVariables` is false, or when `throwOnUnresolvedEntityKeys` is set and the base request or a recipient carries an entity key that no configured lookup can resolve.
  */ function expandMailgunRecipientBatchSendTargetRequestFactory(config) {
     var _inputBaseRequest_from, _inputBaseRequest_replyTo;
-    var inputBaseRequest = config.request, useSubjectFromRecipientUserVariables = config.useSubjectFromRecipientUserVariables, allowSingleRecipientBatchSendRequests = config.allowSingleRecipientBatchSendRequests, recipientVariablesConfig = config.recipientVariablesConfig, mailgunRecipientBatchSendTargetEntityKeyRecipientLookup = config.mailgunRecipientBatchSendTargetEntityKeyRecipientLookup, overrideCarbonCopyVariablesWithCarbonCopyKeyRecipients = config.overrideCarbonCopyVariablesWithCarbonCopyKeyRecipients;
+    var inputBaseRequest = config.request, useSubjectFromRecipientUserVariables = config.useSubjectFromRecipientUserVariables, allowSingleRecipientBatchSendRequests = config.allowSingleRecipientBatchSendRequests, recipientVariablesConfig = config.recipientVariablesConfig, mailgunRecipientBatchSendTargetEntityKeyRecipientLookup = config.mailgunRecipientBatchSendTargetEntityKeyRecipientLookup, overrideCarbonCopyVariablesWithCarbonCopyKeyRecipients = config.overrideCarbonCopyVariablesWithCarbonCopyKeyRecipients, overrideAttachmentsWithRecipientAttachments = config.overrideAttachmentsWithRecipientAttachments, throwOnUnresolvedEntityKeys = config.throwOnUnresolvedEntityKeys;
     var defaultSubject = inputBaseRequest.subject;
     if (!defaultSubject && !useSubjectFromRecipientUserVariables) {
         throw new Error('defaultSubject must be set when "useSubjectFromRecipientUserVariables" is false');
     }
+    var recipientsMap = mailgunRecipientBatchSendTargetEntityKeyRecipientLookup === null || mailgunRecipientBatchSendTargetEntityKeyRecipientLookup === void 0 ? void 0 : mailgunRecipientBatchSendTargetEntityKeyRecipientLookup.recipientsMap;
+    /**
+     * Returns every entity key on the input that no configured lookup can resolve.
+     *
+     * The map is consulted directly because neither getRecipientOrDefaultForKey() nor getRecipientsForKeys() reports a
+     * miss; both fall back silently. A partially resolved ccKeys/bccKeys counts too, since a single mistyped key there
+     * drops a carbon copy recipient just as quietly.
+     *
+     * @param carrier - The base request or recipient whose keys are checked.
+     * @returns The unresolved keys, paired with the field each was found on.
+     */ function unresolvedEntityKeysFor(carrier) {
+        var unresolved = [];
+        function collectUnresolvedKeys(field, keys) {
+            if (keys != null) {
+                asArray(keys).forEach(function(key) {
+                    if (!(recipientsMap === null || recipientsMap === void 0 ? void 0 : recipientsMap.has(key))) {
+                        unresolved.push({
+                            field: field,
+                            key: key
+                        });
+                    }
+                });
+            }
+        }
+        collectUnresolvedKeys('fromKey', carrier.fromKey);
+        collectUnresolvedKeys('replyToKey', carrier.replyToKey);
+        collectUnresolvedKeys('ccKeys', carrier.ccKeys);
+        collectUnresolvedKeys('bccKeys', carrier.bccKeys);
+        return unresolved;
+    }
+    /**
+     * Throws or warns about unresolved entity keys, depending on throwOnUnresolvedEntityKeys.
+     *
+     * Reports once for the whole set rather than once per key, so a large batch that shares one bad key does not emit a
+     * line per recipient.
+     *
+     * @param source - Description of what carried the keys, used in the message.
+     * @param unresolved - The unresolved keys to report. Nothing is reported when empty.
+     * @throws {Error} When throwOnUnresolvedEntityKeys is set and at least one unresolved key was given.
+     */ function reportUnresolvedEntityKeys(source, unresolved) {
+        if (unresolved.length > 0) {
+            var describedKeys = Array.from(new Set(unresolved.map(function(param) {
+                var field = param.field, key = param.key;
+                return "".concat(field, ': "').concat(key, '"');
+            }))).join(', ');
+            var reason = recipientsMap ? 'they are absent from the configured mailgunRecipientBatchSendTargetEntityKeyRecipientLookup' : 'no mailgunRecipientBatchSendTargetEntityKeyRecipientLookup was configured';
+            var message = "expandMailgunRecipientBatchSendTargetRequestFactory(): ".concat(source, " specified entity keys that cannot be resolved [").concat(describedKeys, "] because ").concat(reason, ". Unresolved keys are ignored in favor of the base request's values, which sends a valid email from the wrong address.");
+            if (throwOnUnresolvedEntityKeys) {
+                throw new Error(message);
+            } else {
+                console.warn(message);
+            }
+        }
+    }
+    reportUnresolvedEntityKeys('the base request', unresolvedEntityKeysFor(inputBaseRequest));
     /**
      * Returns the carbon copy recipients, based on the input.
      *
@@ -1640,11 +1695,33 @@ function _unsupported_iterable_to_array(o, minLen) {
     });
     var baseRequestFrom = (_inputBaseRequest_from = inputBaseRequest.from) !== null && _inputBaseRequest_from !== void 0 ? _inputBaseRequest_from : mailgunRecipientBatchSendTargetEntityKeyRecipientLookup === null || mailgunRecipientBatchSendTargetEntityKeyRecipientLookup === void 0 ? void 0 : mailgunRecipientBatchSendTargetEntityKeyRecipientLookup.getRecipientOrDefaultForKey(inputBaseRequest.fromKey);
     var baseRequestReplyTo = (_inputBaseRequest_replyTo = inputBaseRequest.replyTo) !== null && _inputBaseRequest_replyTo !== void 0 ? _inputBaseRequest_replyTo : mailgunRecipientBatchSendTargetEntityKeyRecipientLookup === null || mailgunRecipientBatchSendTargetEntityKeyRecipientLookup === void 0 ? void 0 : mailgunRecipientBatchSendTargetEntityKeyRecipientLookup.getRecipientOrDefaultForKey(inputBaseRequest.replyToKey);
+    /**
+     * The attachments every request built by this factory carries, batched or individual.
+     *
+     * Normalized once here so the merge in determineAttachments() has a single array to work from.
+     */ var baseRequestAttachments = inputBaseRequest.attachments ? asArray(inputBaseRequest.attachments) : undefined;
+    /**
+     * Returns the attachments for an individual request, merging the base request's attachments with the recipient's.
+     *
+     * Will return undefined if the array would be empty.
+     *
+     * @param recipientAttachments - The recipient's own attachments, if any.
+     * @returns The attachments for the request, or undefined when there are none.
+     */ function determineAttachments(recipientAttachments) {
+        var attachments;
+        if (recipientAttachments === null || recipientAttachments === void 0 ? void 0 : recipientAttachments.length) {
+            attachments = overrideAttachmentsWithRecipientAttachments ? recipientAttachments : _to_consumable_array(baseRequestAttachments !== null && baseRequestAttachments !== void 0 ? baseRequestAttachments : []).concat(_to_consumable_array(recipientAttachments));
+        } else {
+            attachments = baseRequestAttachments;
+        }
+        return (attachments === null || attachments === void 0 ? void 0 : attachments.length) ? attachments : undefined;
+    }
     var baseRequest = _object_spread_props(_object_spread({}, inputBaseRequest), {
         from: baseRequestFrom,
         replyTo: baseRequestReplyTo,
         cc: baseRequestCc,
-        bcc: baseRequestBcc
+        bcc: baseRequestBcc,
+        attachments: baseRequestAttachments
     });
     delete baseRequest.fromKey;
     delete baseRequest.replyToKey;
@@ -1652,6 +1729,7 @@ function _unsupported_iterable_to_array(o, minLen) {
     delete baseRequest.bccKeys;
     var configAllowBatchSend = baseRequest.batchSend !== false;
     return function(inputRecipients) {
+        reportUnresolvedEntityKeys('a recipient', inputRecipients.flatMap(unresolvedEntityKeysFor));
         // Process recipients to resolve keys
         var recipients = inputRecipients.map(function(recipient) {
             var from = recipient.from;
@@ -1680,7 +1758,8 @@ function _unsupported_iterable_to_array(o, minLen) {
                 from: from,
                 replyTo: replyTo,
                 cc: cc,
-                bcc: bcc
+                bcc: bcc,
+                attachments: recipient.attachments ? asArray(recipient.attachments) : undefined
             });
             return result;
         });
@@ -1688,9 +1767,11 @@ function _unsupported_iterable_to_array(o, minLen) {
         var nonBatchSendRequests = [];
         var batchSendRequestRecipients = [];
         recipients.forEach(function(recipient) {
-            var _recipient_cc, _recipient_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) {
+            var _recipient_cc, _recipient_bcc, _recipient_attachments;
+            // attachments live on the REQUEST and a MailgunRecipient has no attachment slot, so a recipient carrying its own
+            // cannot ride a shared to[] -- every other recipient of that request would receive it too.
+            var recipientRequiresOwnRequest = 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) || ((_recipient_attachments = recipient.attachments) === null || _recipient_attachments === void 0 ? void 0 : _recipient_attachments.length));
+            if (allowBatchSend && !recipientRequiresOwnRequest) {
                 // add to batch send recipients
                 batchSendRequestRecipients.push(recipient);
             } else {
@@ -1708,6 +1789,7 @@ function _unsupported_iterable_to_array(o, minLen) {
                     to: recipient,
                     cc: cc,
                     bcc: bcc,
+                    attachments: determineAttachments(recipient.attachments),
                     subject: subject,
                     batchSend: false // explicitly disable batch send for non-batch requests
                 });
@@ -1729,6 +1811,7 @@ function _unsupported_iterable_to_array(o, minLen) {
                     replyTo: firstRecipient.replyTo,
                     recipientVariablesConfig: (_baseRequest_recipientVariablesConfig = baseRequest.recipientVariablesConfig) !== null && _baseRequest_recipientVariablesConfig !== void 0 ? _baseRequest_recipientVariablesConfig : recipientVariablesConfig,
                     to: groupRecipients,
+                    attachments: baseRequestAttachments,
                     subject: subject,
                     batchSend: true
                 });

package/mailgun/package.json

@@ -1,13 +1,13 @@
 {
   "name": "@dereekb/nestjs/mailgun",
-  "version": "13.41.0",
+  "version": "13.42.0",
   "type": "module",
   "peerDependencies": {
-    "@dereekb/date": "13.41.0",
-    "@dereekb/model": "13.41.0",
-    "@dereekb/nestjs": "13.41.0",
-    "@dereekb/rxjs": "13.41.0",
-    "@dereekb/util": "13.41.0",
+    "@dereekb/date": "13.42.0",
+    "@dereekb/model": "13.42.0",
+    "@dereekb/nestjs": "13.42.0",
+    "@dereekb/rxjs": "13.42.0",
+    "@dereekb/util": "13.42.0",
     "@nestjs/common": "^11.1.19",
     "@nestjs/config": "^4.0.4",
     "form-data": "^4.0.5",

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

@@ -72,6 +72,18 @@ export interface MailgunFileAttachment {
      * File data as a buffer or string.
      */
     readonly data: CustomFileData;
+    /**
+     * Content-Type applied to this MIME part, including any parameters.
+     *
+     * Defaulted by Mailgun (to an "attachment"-flavoured octet stream) when absent, which is right for an
+     * ordinary file. It is NOT right for a part whose type is what makes the receiving client act on it:
+     * an iTIP calendar invite is only auto-processed when its part is typed
+     * `text/calendar; method=REQUEST; charset=utf-8` — the same bytes typed as an octet stream render as a
+     * paperclip instead of an invitation.
+     *
+     * Passes through to mailgun.js's `CustomFile.contentType`, which is appended to the form-data part.
+     */
+    readonly contentType?: Maybe<string>;
 }
 export interface MailgunTemplateEmailRequestTestingParameters {
     /**
@@ -86,8 +98,11 @@ export interface MailgunTemplateEmailRequestTestingParameters {
 export interface MailgunTemplateEmailRequest extends MailgunEmailRequest, MailgunTemplateEmailRequestTestingParameters {
     /**
      * Attachment(s) to send with the email.
+     *
+     * Every recipient of the request receives them, so a payload meant for one recipient belongs on that recipient's
+     * MailgunRecipientBatchSendTarget "attachments" instead, which expands into its own request.
      */
-    readonly attachments?: ArrayOrValue<MailgunFileAttachment>;
+    readonly attachments?: Maybe<ArrayOrValue<MailgunFileAttachment>>;
     /**
      * Apply/override output message data parameters directly.
      */

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

@@ -1,5 +1,5 @@
 import { type Maybe, type NameEmailPair, type ArrayOrValue } from '@dereekb/util';
-import { type MailgunTemplateEmailRequestRecipientVariablesConfig, type MailgunRecipient, type MailgunTemplateEmailRequest } from './mailgun';
+import { type MailgunTemplateEmailRequestRecipientVariablesConfig, type MailgunFileAttachment, type MailgunRecipient, type MailgunTemplateEmailRequest } from './mailgun';
 /**
  * The default template subject to use when batch sending emails.
  *
@@ -65,6 +65,18 @@ export interface MailgunRecipientBatchSendTarget extends MailgunRecipient {
      * Are merged with bcc when building the request.
      */
     readonly bccKeys?: Maybe<ArrayOrValue<MailgunRecipientBatchSendTargetEntityKey>>;
+    /**
+     * Attachment(s) to send to only this recipient.
+     *
+     * Attachments live on the REQUEST rather than the recipient, so a target that carries any is expanded into its own
+     * request with batch sending disabled, which is the same treatment cc/bcc receive. That is what lets a per-recipient
+     * payload -- an iTIP invite whose ATTENDEE names one address, for instance -- ride the same expansion as the
+     * recipients that still batch.
+     *
+     * Are merged with the base request's attachments when building the request, unless
+     * "overrideAttachmentsWithRecipientAttachments" is set.
+     */
+    readonly attachments?: Maybe<ArrayOrValue<MailgunFileAttachment>>;
 }
 /**
  * Composite key from the (lowercased) from/replyTo email addresses used to group MailgunRecipientBatchSendTarget values.
@@ -118,9 +130,35 @@ export interface ExpandMailgunRecipientBatchSendTargetRequestFactoryConfig {
      * Defaults to false.
      */
     readonly overrideCarbonCopyVariablesWithCarbonCopyKeyRecipients?: Maybe<boolean>;
+    /**
+     * Whether or not to override the base request's attachments with the recipient's attachments.
+     *
+     * If true, a recipient that carries its own attachments sends ONLY those. By default the two are merged, with the
+     * base request's attachments first.
+     *
+     * Only affects the individual requests that a recipient with attachments is expanded into. A batched request's
+     * recipients carry no attachments of their own by definition, so it always sends exactly the base request's.
+     *
+     * Defaults to false.
+     */
+    readonly overrideAttachmentsWithRecipientAttachments?: Maybe<boolean>;
+    /**
+     * Whether or not to throw when an entity key cannot be resolved, either because no lookup is configured or because
+     * the key is absent from the configured lookup's map.
+     *
+     * An unresolved key is invisible downstream: from/replyTo fall back to the base request, and from there to the
+     * Mailgun service's default sender, which produces a perfectly VALID message sent from the WRONG address.
+     * convertMailgunTemplateEmailRequestToMailgunMessageData() validates only batch sending against cc/bcc, the batch
+     * recipient ceiling, and doubly-specified attachments, so it cannot catch this.
+     *
+     * Defaults to false, in which case the unresolved keys are reported once via console.warn and the fallback behavior
+     * is kept.
+     */
+    readonly throwOnUnresolvedEntityKeys?: Maybe<boolean>;
 }
 /**
- * Expands each of the input MailgunRecipientTargetWithCarbonCopyData recipients into individual (or grouped, if no cc/bcc is present on the input recipient) MailgunTemplateEmailRequest objects, based on the input configuration.
+ * Expands each of the input MailgunRecipientBatchSendTarget recipients into individual (or grouped, if no cc/bcc or
+ * attachments are present on the input recipient) MailgunTemplateEmailRequest objects, based on the input configuration.
  */
 export type ExpandMailgunRecipientBatchSendTargetRequestFactory = (recipients: MailgunRecipientBatchSendTarget[]) => MailgunTemplateEmailRequest[];
 /**
@@ -128,7 +166,7 @@ export type ExpandMailgunRecipientBatchSendTargetRequestFactory = (recipients: M
  *
  * @param config - Factory configuration providing the base request, recipient lookup, and per-recipient variable handling.
  * @returns A factory that expands `MailgunRecipientBatchSendTarget` lists into individual `MailgunTemplateEmailRequest` objects.
- * @throws {Error} When no subject is configured and `useSubjectFromRecipientUserVariables` is false.
+ * @throws {Error} When no subject is configured and `useSubjectFromRecipientUserVariables` is false, or when `throwOnUnresolvedEntityKeys` is set and the base request or a recipient carries an entity key that no configured lookup can resolve.
  */
 export declare function expandMailgunRecipientBatchSendTargetRequestFactory(config: ExpandMailgunRecipientBatchSendTargetRequestFactoryConfig): ExpandMailgunRecipientBatchSendTargetRequestFactory;
 /**

package/openai/package.json

@@ -1,13 +1,13 @@
 {
   "name": "@dereekb/nestjs/openai",
-  "version": "13.41.0",
+  "version": "13.42.0",
   "type": "module",
   "peerDependencies": {
-    "@dereekb/date": "13.41.0",
-    "@dereekb/model": "13.41.0",
-    "@dereekb/nestjs": "13.41.0",
-    "@dereekb/rxjs": "13.41.0",
-    "@dereekb/util": "13.41.0",
+    "@dereekb/date": "13.42.0",
+    "@dereekb/model": "13.42.0",
+    "@dereekb/nestjs": "13.42.0",
+    "@dereekb/rxjs": "13.42.0",
+    "@dereekb/util": "13.42.0",
     "@nestjs/common": "^11.1.19",
     "@nestjs/config": "^4.0.4",
     "express": "^5.2.1",

package/openrouter/package.json

@@ -1,10 +1,10 @@
 {
   "name": "@dereekb/nestjs/openrouter",
-  "version": "13.41.0",
+  "version": "13.42.0",
   "type": "module",
   "peerDependencies": {
-    "@dereekb/util": "13.41.0",
-    "@dereekb/nestjs": "13.41.0",
+    "@dereekb/util": "13.42.0",
+    "@dereekb/nestjs": "13.42.0",
     "@nestjs/common": "^11.1.19",
     "@nestjs/config": "^4.0.4",
     "express": "^5.2.1",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dereekb/nestjs",
-  "version": "13.41.0",
+  "version": "13.42.0",
   "type": "module",
   "exports": {
     "./stripe": {
@@ -51,8 +51,8 @@
     }
   },
   "peerDependencies": {
-    "@dereekb/rxjs": "13.41.0",
-    "@dereekb/util": "13.41.0",
+    "@dereekb/rxjs": "13.42.0",
+    "@dereekb/util": "13.42.0",
     "@nestjs/common": "^11.1.19",
     "@nestjs/config": "^4.0.4",
     "@typeform/api-client": "^2.10.2",

package/stripe/package.json

@@ -1,13 +1,13 @@
 {
   "name": "@dereekb/nestjs/stripe",
-  "version": "13.41.0",
+  "version": "13.42.0",
   "type": "module",
   "peerDependencies": {
-    "@dereekb/date": "13.41.0",
-    "@dereekb/model": "13.41.0",
-    "@dereekb/nestjs": "13.41.0",
-    "@dereekb/rxjs": "13.41.0",
-    "@dereekb/util": "13.41.0",
+    "@dereekb/date": "13.42.0",
+    "@dereekb/model": "13.42.0",
+    "@dereekb/nestjs": "13.42.0",
+    "@dereekb/rxjs": "13.42.0",
+    "@dereekb/util": "13.42.0",
     "@nestjs/common": "^11.1.19",
     "@nestjs/config": "^4.0.4",
     "express": "^5.2.1",

package/twilio/package.json

@@ -1,13 +1,13 @@
 {
   "name": "@dereekb/nestjs/twilio",
-  "version": "13.41.0",
+  "version": "13.42.0",
   "type": "module",
   "peerDependencies": {
-    "@dereekb/date": "13.41.0",
-    "@dereekb/model": "13.41.0",
-    "@dereekb/nestjs": "13.41.0",
-    "@dereekb/rxjs": "13.41.0",
-    "@dereekb/util": "13.41.0",
+    "@dereekb/date": "13.42.0",
+    "@dereekb/model": "13.42.0",
+    "@dereekb/nestjs": "13.42.0",
+    "@dereekb/rxjs": "13.42.0",
+    "@dereekb/util": "13.42.0",
     "@nestjs/common": "^11.1.19",
     "@nestjs/config": "^4.0.4",
     "express": "^5.2.1",

package/typeform/package.json

@@ -1,13 +1,13 @@
 {
   "name": "@dereekb/nestjs/typeform",
-  "version": "13.41.0",
+  "version": "13.42.0",
   "type": "module",
   "peerDependencies": {
-    "@dereekb/date": "13.41.0",
-    "@dereekb/model": "13.41.0",
-    "@dereekb/nestjs": "13.41.0",
-    "@dereekb/rxjs": "13.41.0",
-    "@dereekb/util": "13.41.0",
+    "@dereekb/date": "13.42.0",
+    "@dereekb/model": "13.42.0",
+    "@dereekb/nestjs": "13.42.0",
+    "@dereekb/rxjs": "13.42.0",
+    "@dereekb/util": "13.42.0",
     "@nestjs/common": "^11.1.19",
     "@nestjs/config": "^4.0.4",
     "@typeform/api-client": "^2.10.2",

package/vapiai/package.json

@@ -1,13 +1,13 @@
 {
   "name": "@dereekb/nestjs/vapiai",
-  "version": "13.41.0",
+  "version": "13.42.0",
   "type": "module",
   "peerDependencies": {
-    "@dereekb/date": "13.41.0",
-    "@dereekb/model": "13.41.0",
-    "@dereekb/nestjs": "13.41.0",
-    "@dereekb/rxjs": "13.41.0",
-    "@dereekb/util": "13.41.0",
+    "@dereekb/date": "13.42.0",
+    "@dereekb/model": "13.42.0",
+    "@dereekb/nestjs": "13.42.0",
+    "@dereekb/rxjs": "13.42.0",
+    "@dereekb/util": "13.42.0",
     "@nestjs/common": "^11.1.19",
     "@nestjs/config": "^4.0.4",
     "@vapi-ai/server-sdk": "^0.11.0",