@dereekb/nestjs 14.14.0 → 14.15.0

package/eslint/package.json

@@ -1,10 +1,10 @@
 {
   "name": "@dereekb/nestjs/eslint",
-  "version": "14.14.0",
+  "version": "14.15.0",
   "sideEffects": false,
   "type": "module",
   "peerDependencies": {
-    "@dereekb/util": "14.14.0",
+    "@dereekb/util": "14.15.0",
     "@typescript-eslint/utils": "8.69.0"
   },
   "devDependencies": {

package/mailgun/index.esm.js

@@ -772,6 +772,22 @@ function _unsupported_iterable_to_array$1(o, minLen) {
     MailgunEventSeverity["PERMANENT"] = "permanent";
     MailgunEventSeverity["TEMPORARY"] = "temporary";
 })(MailgunEventSeverity || (MailgunEventSeverity = {}));
+/**
+ * The domain suppression lists an address can be on.
+ *
+ * The values are the list names the Mailgun Suppressions API takes.
+ */ var MailgunSuppressionList;
+(function(MailgunSuppressionList) {
+    /**
+     * Addresses a previous message hard-bounced from.
+     */ MailgunSuppressionList["BOUNCES"] = "bounces";
+    /**
+     * Addresses that reported a message as spam.
+     */ MailgunSuppressionList["COMPLAINTS"] = "complaints";
+    /**
+     * Addresses that unsubscribed, from all mail or from specific tags.
+     */ MailgunSuppressionList["UNSUBSCRIBES"] = "unsubscribes";
+})(MailgunSuppressionList || (MailgunSuppressionList = {}));
 /**
  * True if any suppression record was found for the address.
  *
@@ -853,13 +869,13 @@ function _unsupported_iterable_to_array$1(o, minLen) {
                         Promise.all([
                             //
                             readSuppression(function() {
-                                return suppressions.get(domain, 'bounces', email);
+                                return suppressions.get(domain, MailgunSuppressionList.BOUNCES, email);
                             }),
                             readSuppression(function() {
-                                return suppressions.get(domain, 'complaints', email);
+                                return suppressions.get(domain, MailgunSuppressionList.COMPLAINTS, email);
                             }),
                             readSuppression(function() {
-                                return suppressions.get(domain, 'unsubscribes', email);
+                                return suppressions.get(domain, MailgunSuppressionList.UNSUBSCRIBES, email);
                             })
                         ])
                     ];
@@ -880,6 +896,79 @@ function _unsupported_iterable_to_array$1(o, minLen) {
         });
     })();
 }
+/**
+ * Removes an address from one of the domain's suppression lists, so Mailgun delivers to it again.
+ *
+ * An unsubscribe record is removed in full, including every tag it covers.
+ *
+ * Failure-tolerant like the read helpers in this module. Mailgun responds 404 when the address is not on
+ * the list, and that counts as cleared, since the goal (the address is not suppressed) is already met. Any
+ * other failure is returned as `cleared: false` with the error.
+ *
+ * @param api - The Mailgun API.
+ * @param email - The address to remove.
+ * @param list - The suppression list to remove it from.
+ * @returns What happened to the address on that list.
+ *
+ * @example
+ * ```ts
+ * const result = await mailgunRemoveSuppressionForRecipient(api, 'user@example.com', MailgunSuppressionList.UNSUBSCRIBES);
+ *
+ * if (!result.cleared) {
+ *   console.log(`could not resubscribe: ${result.error}`);
+ * }
+ * ```
+ */ function mailgunRemoveSuppressionForRecipient(api, email, list) {
+    return _async_to_generator$1(function() {
+        var result, e, notFound;
+        return _ts_generator$1(this, function(_state) {
+            switch(_state.label){
+                case 0:
+                    _state.trys.push([
+                        0,
+                        2,
+                        ,
+                        3
+                    ]);
+                    return [
+                        4,
+                        api.suppressions.destroy(api.domain, list, email)
+                    ];
+                case 1:
+                    _state.sent();
+                    result = {
+                        list: list,
+                        cleared: true
+                    };
+                    return [
+                        3,
+                        3
+                    ];
+                case 2:
+                    e = _state.sent();
+                    notFound = (e === null || e === void 0 ? void 0 : e.status) === 404;
+                    result = notFound ? {
+                        list: list,
+                        cleared: true,
+                        notFound: notFound
+                    } : {
+                        list: list,
+                        cleared: false,
+                        error: "".concat(e)
+                    };
+                    return [
+                        3,
+                        3
+                    ];
+                case 3:
+                    return [
+                        2,
+                        result
+                    ];
+            }
+        });
+    })();
+}
 /**
  * Reads the most recent Mailgun events for a recipient address, newest first.
  *
@@ -915,6 +1004,61 @@ function _unsupported_iterable_to_array$1(o, minLen) {
         });
     })();
 }
+/**
+ * The default distance from the reference time that {@link mailgunEventForRecipientNear} searches.
+ */ var DEFAULT_MAILGUN_EVENT_NEAR_WINDOW_MINUTES = 60;
+/**
+ * Finds the recipient's event of a given kind closest to a point in time.
+ *
+ * Used to connect a suppression record to the event that created it. A suppression only records when it
+ * happened, while the `unsubscribed` / `complained` event that triggered it also carries the message it
+ * was triggered from, such as that message's subject.
+ *
+ * The search sends both `begin` and `end`, so Mailgun reads the range in ascending order and does not rely
+ * on the `ascending` flag. An empty result is normal. Mailgun keeps events only for the plan's retention
+ * period, and a suppression added through the API or the dashboard has no event at all.
+ *
+ * @param api - The Mailgun API.
+ * @param email - The recipient address.
+ * @param config - The event name, the time to search around, and the window.
+ * @returns The matching event closest to `at`, or undefined if there is none or the lookup failed.
+ */ function mailgunEventForRecipientNear(api, email, config) {
+    return _async_to_generator$1(function() {
+        var event, at, inputWindowMinutes, windowMs, atTime, events, closest, closestDistance;
+        return _ts_generator$1(this, function(_state) {
+            switch(_state.label){
+                case 0:
+                    event = config.event, at = config.at, inputWindowMinutes = config.windowMinutes;
+                    windowMs = (inputWindowMinutes !== null && inputWindowMinutes !== void 0 ? inputWindowMinutes : DEFAULT_MAILGUN_EVENT_NEAR_WINDOW_MINUTES) * 60 * 1000;
+                    atTime = at.getTime();
+                    return [
+                        4,
+                        mailgunEventsForQuery(api, {
+                            recipient: email,
+                            event: event,
+                            begin: new Date(atTime - windowMs).toUTCString(),
+                            end: new Date(atTime + windowMs).toUTCString(),
+                            limit: 25
+                        })
+                    ];
+                case 1:
+                    events = _state.sent();
+                    closestDistance = Number.POSITIVE_INFINITY;
+                    events.forEach(function(x) {
+                        var distance = Math.abs(mailgunDomainEventDate(x).getTime() - atTime);
+                        if (distance < closestDistance) {
+                            closest = x;
+                            closestDistance = distance;
+                        }
+                    });
+                    return [
+                        2,
+                        closest
+                    ];
+            }
+        });
+    })();
+}
 /**
  * Strips the angle brackets Mailgun's send response wraps a message id in.
  *
@@ -1828,4 +1972,4 @@ function _unsupported_iterable_to_array(o, minLen) {
     };
 }
 
-export { DEFAULT_MAILGUN_RECENT_EVENTS_LIMIT, DEFAULT_MAILGUN_RECENT_EVENTS_WINDOW_DAYS, DEFAULT_RECIPIENT_VARIABLE_PREFIX, MAILGUN_BATCH_SEND_RECIPIENT_SUBJECT_TEMPLATE, MAILGUN_REPLY_TO_EMAIL_HEADER_DATA_VARIABLE_KEY, MAX_BATCH_SEND_RECIPIENTS, MailgunApi, MailgunEventName, MailgunEventSeverity, MailgunService, MailgunServiceModule, bareMailgunMessageId, convertMailgunRecipientToString, convertMailgunRecipientsToStrings, convertMailgunTemplateEmailRequestToMailgunMessageData, encodeMailgunTemplateVariableValue, expandMailgunRecipientBatchSendTargetRequestFactory, hasAnyMailgunRecipientSuppression, mailgunDomainEventAge, mailgunDomainEventDate, mailgunDomainEventFailureReason, mailgunDomainState, mailgunEventsForMessageId, mailgunEventsForQuery, mailgunRecentEventsForRecipient, mailgunRecipientBatchSendTargetEntityKeyRecipientLookup, mailgunRecipientBatchSendTargetFromReplyToBatchGroupKey, mailgunServiceConfigFactory, mailgunSuppressionsForRecipient, mailgunValidateEmail };
+export { DEFAULT_MAILGUN_EVENT_NEAR_WINDOW_MINUTES, DEFAULT_MAILGUN_RECENT_EVENTS_LIMIT, DEFAULT_MAILGUN_RECENT_EVENTS_WINDOW_DAYS, DEFAULT_RECIPIENT_VARIABLE_PREFIX, MAILGUN_BATCH_SEND_RECIPIENT_SUBJECT_TEMPLATE, MAILGUN_REPLY_TO_EMAIL_HEADER_DATA_VARIABLE_KEY, MAX_BATCH_SEND_RECIPIENTS, MailgunApi, MailgunEventName, MailgunEventSeverity, MailgunService, MailgunServiceModule, MailgunSuppressionList, bareMailgunMessageId, convertMailgunRecipientToString, convertMailgunRecipientsToStrings, convertMailgunTemplateEmailRequestToMailgunMessageData, encodeMailgunTemplateVariableValue, expandMailgunRecipientBatchSendTargetRequestFactory, hasAnyMailgunRecipientSuppression, mailgunDomainEventAge, mailgunDomainEventDate, mailgunDomainEventFailureReason, mailgunDomainState, mailgunEventForRecipientNear, mailgunEventsForMessageId, mailgunEventsForQuery, mailgunRecentEventsForRecipient, mailgunRecipientBatchSendTargetEntityKeyRecipientLookup, mailgunRecipientBatchSendTargetFromReplyToBatchGroupKey, mailgunRemoveSuppressionForRecipient, mailgunServiceConfigFactory, mailgunSuppressionsForRecipient, mailgunValidateEmail };

package/mailgun/package.json

@@ -1,14 +1,14 @@
 {
   "name": "@dereekb/nestjs/mailgun",
-  "version": "14.14.0",
+  "version": "14.15.0",
   "sideEffects": false,
   "type": "module",
   "peerDependencies": {
-    "@dereekb/date": "14.14.0",
-    "@dereekb/model": "14.14.0",
-    "@dereekb/nestjs": "14.14.0",
-    "@dereekb/rxjs": "14.14.0",
-    "@dereekb/util": "14.14.0",
+    "@dereekb/date": "14.15.0",
+    "@dereekb/model": "14.15.0",
+    "@dereekb/nestjs": "14.15.0",
+    "@dereekb/rxjs": "14.15.0",
+    "@dereekb/util": "14.15.0",
     "@nestjs/common": "^12.0.1",
     "@nestjs/config": "^12.0.0",
     "form-data": "^4.0.5",

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

@@ -7,8 +7,12 @@
  * anything. They are all failure-tolerant: a missing suppression record or an
  * unreachable API surfaces as an absent/empty result rather than a thrown error, so a
  * diagnostic routine can report what it could learn instead of aborting.
+ *
+ * The one write here is {@link mailgunRemoveSuppressionForRecipient}, the remedy for a
+ * suppression the diagnosis found. It is failure-tolerant in the same way, reporting what
+ * happened instead of throwing.
  */
-import { type EmailAddress, type Maybe, type Milliseconds } from '@dereekb/util';
+import { type EmailAddress, type Maybe, type Milliseconds, type Minutes } from '@dereekb/util';
 import { type MailgunApi } from './mailgun.api';
 import { type MailgunBounceSuppression, type MailgunComplaintSuppression, type MailgunDomainEvent, type MailgunEmailValidationResult, type MailgunEventsQuery, type MailgunUnsubscribeSuppression } from './mailgun.type';
 /**
@@ -44,6 +48,25 @@ export declare enum MailgunEventSeverity {
     PERMANENT = "permanent",
     TEMPORARY = "temporary"
 }
+/**
+ * The domain suppression lists an address can be on.
+ *
+ * The values are the list names the Mailgun Suppressions API takes.
+ */
+export declare enum MailgunSuppressionList {
+    /**
+     * Addresses a previous message hard-bounced from.
+     */
+    BOUNCES = "bounces",
+    /**
+     * Addresses that reported a message as spam.
+     */
+    COMPLAINTS = "complaints",
+    /**
+     * Addresses that unsubscribed, from all mail or from specific tags.
+     */
+    UNSUBSCRIBES = "unsubscribes"
+}
 /**
  * The suppression records found for a single address across a domain's suppression lists.
  *
@@ -79,6 +102,52 @@ export declare function hasAnyMailgunRecipientSuppression(suppressions: MailgunR
  * ```
  */
 export declare function mailgunSuppressionsForRecipient(api: MailgunApi, email: EmailAddress): Promise<MailgunRecipientSuppressions>;
+/**
+ * The outcome of {@link mailgunRemoveSuppressionForRecipient}.
+ */
+export interface MailgunRemoveSuppressionForRecipientResult {
+    /**
+     * The list the address was removed from.
+     */
+    readonly list: MailgunSuppressionList;
+    /**
+     * True when the address is no longer on the list, either because it was just removed or because it was
+     * not on the list in the first place.
+     */
+    readonly cleared: boolean;
+    /**
+     * True when the address was not on the list to begin with.
+     */
+    readonly notFound?: Maybe<boolean>;
+    /**
+     * Why the removal failed, when it did.
+     */
+    readonly error?: Maybe<string>;
+}
+/**
+ * Removes an address from one of the domain's suppression lists, so Mailgun delivers to it again.
+ *
+ * An unsubscribe record is removed in full, including every tag it covers.
+ *
+ * Failure-tolerant like the read helpers in this module. Mailgun responds 404 when the address is not on
+ * the list, and that counts as cleared, since the goal (the address is not suppressed) is already met. Any
+ * other failure is returned as `cleared: false` with the error.
+ *
+ * @param api - The Mailgun API.
+ * @param email - The address to remove.
+ * @param list - The suppression list to remove it from.
+ * @returns What happened to the address on that list.
+ *
+ * @example
+ * ```ts
+ * const result = await mailgunRemoveSuppressionForRecipient(api, 'user@example.com', MailgunSuppressionList.UNSUBSCRIBES);
+ *
+ * if (!result.cleared) {
+ *   console.log(`could not resubscribe: ${result.error}`);
+ * }
+ * ```
+ */
+export declare function mailgunRemoveSuppressionForRecipient(api: MailgunApi, email: EmailAddress, list: MailgunSuppressionList): Promise<MailgunRemoveSuppressionForRecipientResult>;
 /**
  * Configuration for reading a recipient's recent Mailgun events.
  */
@@ -115,6 +184,46 @@ export interface MailgunRecentEventsForRecipientConfig {
  * ```
  */
 export declare function mailgunRecentEventsForRecipient(api: MailgunApi, email: EmailAddress, config?: Maybe<MailgunRecentEventsForRecipientConfig>): Promise<MailgunDomainEvent[]>;
+/**
+ * The default distance from the reference time that {@link mailgunEventForRecipientNear} searches.
+ */
+export declare const DEFAULT_MAILGUN_EVENT_NEAR_WINDOW_MINUTES: Minutes;
+/**
+ * Configuration for {@link mailgunEventForRecipientNear}.
+ */
+export interface MailgunEventForRecipientNearConfig {
+    /**
+     * The event name to look for, e.g. {@link MailgunEventName.UNSUBSCRIBED}.
+     */
+    readonly event: string;
+    /**
+     * The time the event is expected to have happened.
+     */
+    readonly at: Date;
+    /**
+     * How far either side of `at` to search.
+     *
+     * Defaults to {@link DEFAULT_MAILGUN_EVENT_NEAR_WINDOW_MINUTES}.
+     */
+    readonly windowMinutes?: Maybe<Minutes>;
+}
+/**
+ * Finds the recipient's event of a given kind closest to a point in time.
+ *
+ * Used to connect a suppression record to the event that created it. A suppression only records when it
+ * happened, while the `unsubscribed` / `complained` event that triggered it also carries the message it
+ * was triggered from, such as that message's subject.
+ *
+ * The search sends both `begin` and `end`, so Mailgun reads the range in ascending order and does not rely
+ * on the `ascending` flag. An empty result is normal. Mailgun keeps events only for the plan's retention
+ * period, and a suppression added through the API or the dashboard has no event at all.
+ *
+ * @param api - The Mailgun API.
+ * @param email - The recipient address.
+ * @param config - The event name, the time to search around, and the window.
+ * @returns The matching event closest to `at`, or undefined if there is none or the lookup failed.
+ */
+export declare function mailgunEventForRecipientNear(api: MailgunApi, email: EmailAddress, config: MailgunEventForRecipientNearConfig): Promise<Maybe<MailgunDomainEvent>>;
 /**
  * Strips the angle brackets Mailgun's send response wraps a message id in.
  *

package/openai/package.json

@@ -1,14 +1,14 @@
 {
   "name": "@dereekb/nestjs/openai",
-  "version": "14.14.0",
+  "version": "14.15.0",
   "sideEffects": false,
   "type": "module",
   "peerDependencies": {
-    "@dereekb/date": "14.14.0",
-    "@dereekb/model": "14.14.0",
-    "@dereekb/nestjs": "14.14.0",
-    "@dereekb/rxjs": "14.14.0",
-    "@dereekb/util": "14.14.0",
+    "@dereekb/date": "14.15.0",
+    "@dereekb/model": "14.15.0",
+    "@dereekb/nestjs": "14.15.0",
+    "@dereekb/rxjs": "14.15.0",
+    "@dereekb/util": "14.15.0",
     "@nestjs/common": "^12.0.1",
     "@nestjs/config": "^12.0.0",
     "express": "^5.2.1",

package/openrouter/package.json

@@ -1,11 +1,11 @@
 {
   "name": "@dereekb/nestjs/openrouter",
-  "version": "14.14.0",
+  "version": "14.15.0",
   "sideEffects": false,
   "type": "module",
   "peerDependencies": {
-    "@dereekb/util": "14.14.0",
-    "@dereekb/nestjs": "14.14.0",
+    "@dereekb/util": "14.15.0",
+    "@dereekb/nestjs": "14.15.0",
     "@nestjs/common": "^12.0.1",
     "@nestjs/config": "^12.0.0",
     "express": "^5.2.1",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dereekb/nestjs",
-  "version": "14.14.0",
+  "version": "14.15.0",
   "sideEffects": false,
   "type": "module",
   "exports": {
@@ -52,8 +52,8 @@
     }
   },
   "peerDependencies": {
-    "@dereekb/rxjs": "14.14.0",
-    "@dereekb/util": "14.14.0",
+    "@dereekb/rxjs": "14.15.0",
+    "@dereekb/util": "14.15.0",
     "@nestjs/common": "^12.0.1",
     "@nestjs/config": "^12.0.0",
     "@typeform/api-client": "^2.10.2",

package/stripe/package.json

@@ -1,14 +1,14 @@
 {
   "name": "@dereekb/nestjs/stripe",
-  "version": "14.14.0",
+  "version": "14.15.0",
   "sideEffects": false,
   "type": "module",
   "peerDependencies": {
-    "@dereekb/date": "14.14.0",
-    "@dereekb/model": "14.14.0",
-    "@dereekb/nestjs": "14.14.0",
-    "@dereekb/rxjs": "14.14.0",
-    "@dereekb/util": "14.14.0",
+    "@dereekb/date": "14.15.0",
+    "@dereekb/model": "14.15.0",
+    "@dereekb/nestjs": "14.15.0",
+    "@dereekb/rxjs": "14.15.0",
+    "@dereekb/util": "14.15.0",
     "@nestjs/common": "^12.0.1",
     "@nestjs/config": "^12.0.0",
     "express": "^5.2.1",