@dereekb/nestjs 13.30.0 → 13.32.0

package/mailgun/package.json

@@ -1,12 +1,12 @@
 {
   "name": "@dereekb/nestjs/mailgun",
-  "version": "13.30.0",
+  "version": "13.32.0",
   "peerDependencies": {
-    "@dereekb/date": "13.30.0",
-    "@dereekb/model": "13.30.0",
-    "@dereekb/nestjs": "13.30.0",
-    "@dereekb/rxjs": "13.30.0",
-    "@dereekb/util": "13.30.0",
+    "@dereekb/date": "13.32.0",
+    "@dereekb/model": "13.32.0",
+    "@dereekb/nestjs": "13.32.0",
+    "@dereekb/rxjs": "13.32.0",
+    "@dereekb/util": "13.32.0",
     "@nestjs/common": "^11.1.19",
     "@nestjs/config": "^4.0.4",
     "form-data": "^4.0.5",

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

@@ -1,6 +1,7 @@
 export * from './mailgun';
 export * from './mailgun.type';
 export * from './mailgun.api';
+export * from './mailgun.diagnostic';
 export * from './mailgun.service.module';
 export * from './mailgun.service';
 export * from './mailgun.util';

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

@@ -1,12 +1,40 @@
 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';
+import { type MailgunClient, type MailgunDomainsClient, type MailgunEventsClient, type MailgunMessagesClient, type MailgunSuppressionsClient, type MailgunValidationClient } from './mailgun.type';
 export declare class MailgunApi {
     readonly config: MailgunServiceConfig;
     readonly client: MailgunClient;
     constructor(config: MailgunServiceConfig);
     get messages(): MailgunMessagesClient;
+    /**
+     * The domain's suppression lists (bounces, spam complaints, unsubscribes, whitelists).
+     *
+     * An address on the bounce or complaint list is silently dropped by Mailgun on every subsequent send,
+     * which makes this the first thing to check when diagnosing "this recipient stopped receiving email".
+     *
+     * @returns The suppressions client.
+     */
+    get suppressions(): MailgunSuppressionsClient;
+    /**
+     * The domain's event log, used to inspect what actually happened to sent messages
+     * (accepted/delivered/failed/rejected/complained/unsubscribed).
+     *
+     * @returns The events client.
+     */
+    get events(): MailgunEventsClient;
+    /**
+     * Single-address validation.
+     *
+     * @returns The validation client.
+     */
+    get validate(): MailgunValidationClient;
+    /**
+     * Domain administration, used to read the sending domain's verification state.
+     *
+     * @returns The domains client.
+     */
+    get domains(): MailgunDomainsClient;
     get clientUrl(): WebsiteUrl;
     get domain(): MailgunSenderDomainString;
     get sender(): EmailParticipantString;

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

@@ -0,0 +1,216 @@
+/**
+ * @module mailgun.diagnostic
+ *
+ * Read-only helpers over the Mailgun Suppressions, Events, Validation, and Domains APIs.
+ *
+ * These exist to answer "why did this recipient not get the email?" without sending
+ * 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.
+ */
+import { type EmailAddress, type Maybe, type Milliseconds } 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';
+/**
+ * The default number of events to read back when inspecting a recipient's recent activity.
+ */
+export declare const DEFAULT_MAILGUN_RECENT_EVENTS_LIMIT = 25;
+/**
+ * The default window of history to inspect when reading a recipient's recent events.
+ */
+export declare const DEFAULT_MAILGUN_RECENT_EVENTS_WINDOW_DAYS = 30;
+/**
+ * Mailgun event names relevant to delivery diagnosis.
+ *
+ * Mailgun returns these as free-form strings; this enum names the ones that carry
+ * delivery meaning. Unknown values are passed through untouched.
+ */
+export declare enum MailgunEventName {
+    ACCEPTED = "accepted",
+    DELIVERED = "delivered",
+    FAILED = "failed",
+    REJECTED = "rejected",
+    COMPLAINED = "complained",
+    UNSUBSCRIBED = "unsubscribed",
+    OPENED = "opened",
+    CLICKED = "clicked",
+    STORED = "stored"
+}
+/**
+ * Mailgun failure severities. A `permanent` failure will never succeed on retry;
+ * a `temporary` one may.
+ */
+export declare enum MailgunEventSeverity {
+    PERMANENT = "permanent",
+    TEMPORARY = "temporary"
+}
+/**
+ * The suppression records found for a single address across a domain's suppression lists.
+ *
+ * A `bounce` or `complaint` entry means Mailgun will silently drop every subsequent
+ * message to this address until the entry is removed.
+ */
+export interface MailgunRecipientSuppressions {
+    readonly bounce?: Maybe<MailgunBounceSuppression>;
+    readonly complaint?: Maybe<MailgunComplaintSuppression>;
+    readonly unsubscribe?: Maybe<MailgunUnsubscribeSuppression>;
+}
+/**
+ * True if any suppression record was found for the address.
+ *
+ * @param suppressions - The suppression records to check.
+ * @returns True if the address appears on any of the domain's suppression lists.
+ */
+export declare function hasAnyMailgunRecipientSuppression(suppressions: MailgunRecipientSuppressions): boolean;
+/**
+ * Looks up an address across the domain's bounce, complaint, and unsubscribe lists.
+ *
+ * @param api - The Mailgun API.
+ * @param email - The address to look up.
+ * @returns The suppression records found for the address. Absent fields mean the address is not on that list.
+ *
+ * @example
+ * ```ts
+ * const suppressions = await mailgunSuppressionsForRecipient(api, 'user@example.com');
+ *
+ * if (suppressions.bounce) {
+ *   console.log(`suppressed by bounce: ${suppressions.bounce.error}`);
+ * }
+ * ```
+ */
+export declare function mailgunSuppressionsForRecipient(api: MailgunApi, email: EmailAddress): Promise<MailgunRecipientSuppressions>;
+/**
+ * Configuration for reading a recipient's recent Mailgun events.
+ */
+export interface MailgunRecentEventsForRecipientConfig {
+    /**
+     * The maximum number of events to return.
+     *
+     * Defaults to {@link DEFAULT_MAILGUN_RECENT_EVENTS_LIMIT}.
+     */
+    readonly limit?: Maybe<number>;
+    /**
+     * How far back to look.
+     *
+     * Defaults to {@link DEFAULT_MAILGUN_RECENT_EVENTS_WINDOW_DAYS} days.
+     */
+    readonly begin?: Maybe<Date>;
+    /**
+     * Restrict results to a single event name.
+     */
+    readonly event?: Maybe<string>;
+}
+/**
+ * Reads the most recent Mailgun events for a recipient address, newest first.
+ *
+ * @param api - The Mailgun API.
+ * @param email - The recipient address to filter on.
+ * @param config - Optional limit/window/event filters.
+ * @returns The matching events, newest first. Empty if there is no recent activity or the lookup failed.
+ *
+ * @example
+ * ```ts
+ * const events = await mailgunRecentEventsForRecipient(api, 'user@example.com', { limit: 10 });
+ * const lastDelivered = events.find((x) => x.event === MailgunEventName.DELIVERED);
+ * ```
+ */
+export declare function mailgunRecentEventsForRecipient(api: MailgunApi, email: EmailAddress, config?: Maybe<MailgunRecentEventsForRecipientConfig>): Promise<MailgunDomainEvent[]>;
+/**
+ * Strips the angle brackets Mailgun's send response wraps a message id in.
+ *
+ * `messages.create()` returns an id shaped like `<20240101120000.1.abc@domain>`, while the
+ * Events API `message-id` filter expects the bare `20240101120000.1.abc@domain`. Passing the
+ * bracketed form matches nothing.
+ *
+ * @param messageId - A message id in either form.
+ * @returns The message id without surrounding angle brackets.
+ */
+export declare function bareMailgunMessageId(messageId: string): string;
+/**
+ * Reads all Mailgun events recorded for a specific message id.
+ *
+ * Used to resolve the outcome of a message that was already sent — the Events API lags the
+ * send by seconds to minutes, so an empty result means "not known yet", not "not delivered".
+ *
+ * @param api - The Mailgun API.
+ * @param messageId - The message id, with or without angle brackets.
+ * @param config - Optional additional filters (e.g. `recipient` to scope the lookup).
+ * @returns The events recorded for the message. Empty if none are recorded yet or the lookup failed.
+ */
+export declare function mailgunEventsForMessageId(api: MailgunApi, messageId: string, config?: Maybe<Pick<MailgunEventsQuery, 'recipient' | 'begin' | 'limit'>>): Promise<MailgunDomainEvent[]>;
+/**
+ * Runs an arbitrary Events API query, returning an empty list if the lookup fails.
+ *
+ * @param api - The Mailgun API.
+ * @param query - The events query.
+ * @returns The matching events, or an empty array on failure.
+ */
+export declare function mailgunEventsForQuery(api: MailgunApi, query: MailgunEventsQuery): Promise<MailgunDomainEvent[]>;
+/**
+ * The state of a Mailgun sending domain.
+ */
+export interface MailgunDomainState {
+    /**
+     * The domain name.
+     */
+    readonly domain: string;
+    /**
+     * Mailgun's state string for the domain. `active` is healthy; `unverified` means DNS is incomplete.
+     */
+    readonly state?: Maybe<string>;
+    /**
+     * True if the domain is disabled by Mailgun.
+     */
+    readonly disabled?: Maybe<boolean>;
+    /**
+     * True if the state could not be read.
+     */
+    readonly unknown?: Maybe<boolean>;
+}
+/**
+ * Reads the sending domain's state.
+ *
+ * A domain that is not `active` will fail to deliver regardless of recipient configuration,
+ * so this distinguishes a system-wide outage from a per-recipient problem.
+ *
+ * @param api - The Mailgun API.
+ * @returns The domain's state, with `unknown` set if it could not be read.
+ */
+export declare function mailgunDomainState(api: MailgunApi): Promise<MailgunDomainState>;
+/**
+ * Validates a single email address via the Mailgun Validation API.
+ *
+ * Note that validation consumes Mailgun validation quota, so callers should treat this as
+ * an opt-in check rather than something to run on every request.
+ *
+ * @param api - The Mailgun API.
+ * @param email - The address to validate.
+ * @returns The validation result, or undefined if validation is unavailable or failed.
+ */
+export declare function mailgunValidateEmail(api: MailgunApi, email: EmailAddress): Promise<Maybe<MailgunEmailValidationResult>>;
+/**
+ * Converts a Mailgun event's unix-seconds timestamp to a Date.
+ *
+ * @param event - The event.
+ * @returns The event's timestamp as a Date.
+ */
+export declare function mailgunDomainEventDate(event: MailgunDomainEvent): Date;
+/**
+ * The age of a Mailgun event in milliseconds relative to `now`.
+ *
+ * @param event - The event.
+ * @param now - The reference time. Defaults to the current time.
+ * @returns The event's age in milliseconds.
+ */
+export declare function mailgunDomainEventAge(event: MailgunDomainEvent, now?: Date): Milliseconds;
+/**
+ * Extracts the most useful human-readable reason from a failed/rejected Mailgun event.
+ *
+ * Mailgun spreads the explanation across `reason`, `delivery-status.description`, and
+ * `delivery-status.message` depending on how the failure occurred, and any of them may be
+ * empty.
+ *
+ * @param event - The event.
+ * @returns The best available description, or undefined if the event carries none.
+ */
+export declare function mailgunDomainEventFailureReason(event: MailgunDomainEvent): Maybe<string>;

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

@@ -2,4 +2,67 @@ import type Mailgun from 'mailgun.js';
 import { type MailgunClientOptions } from 'node_modules/mailgun.js/Types/Types/MailgunClient/MailgunClientOptions';
 export type MailgunOptions = MailgunClientOptions;
 export type MailgunClient = ReturnType<Mailgun['client']>;
-export type MailgunMessagesClient = ReturnType<Mailgun['client']>['messages'];
+export type MailgunMessagesClient = MailgunClient['messages'];
+export type MailgunSuppressionsClient = MailgunClient['suppressions'];
+export type MailgunEventsClient = MailgunClient['events'];
+export type MailgunValidationClient = MailgunClient['validate'];
+export type MailgunDomainsClient = MailgunClient['domains'];
+/**
+ * A page of events returned by the Mailgun Events API.
+ */
+export type MailgunEventsList = Awaited<ReturnType<MailgunEventsClient['get']>>;
+/**
+ * A single event recorded by Mailgun for a message.
+ *
+ * Carries the delivery outcome (`event`), its `severity` for failures, and a `delivery-status` block
+ * with the receiving server's response.
+ */
+export type MailgunDomainEvent = MailgunEventsList['items'][number];
+/**
+ * Query/filter for the Mailgun Events API.
+ */
+export type MailgunEventsQuery = NonNullable<Parameters<MailgunEventsClient['get']>[1]>;
+/**
+ * The result of validating a single email address via the Mailgun Validation API.
+ */
+export type MailgunEmailValidationResult = Awaited<ReturnType<MailgunValidationClient['get']>>;
+/**
+ * A bounce record on a domain's suppression list.
+ *
+ * While the address has a bounce record, Mailgun drops every message sent to it.
+ */
+export interface MailgunBounceSuppression {
+    readonly address: string;
+    /**
+     * The SMTP status code the receiving server returned.
+     */
+    readonly code: number;
+    /**
+     * The receiving server's explanation of the bounce.
+     */
+    readonly error: string;
+    readonly created_at: Date;
+    readonly type?: string;
+}
+/**
+ * A spam complaint record on a domain's suppression list.
+ *
+ * While the address has a complaint record, Mailgun drops every message sent to it.
+ */
+export interface MailgunComplaintSuppression {
+    readonly address: string;
+    readonly created_at: Date;
+    readonly type?: string;
+}
+/**
+ * An unsubscribe record on a domain's suppression list.
+ */
+export interface MailgunUnsubscribeSuppression {
+    readonly address: string;
+    /**
+     * The message tags the address unsubscribed from. An empty list means all mail.
+     */
+    readonly tags?: string[];
+    readonly created_at: Date;
+    readonly type?: string;
+}

package/openai/package.json

@@ -1,12 +1,12 @@
 {
   "name": "@dereekb/nestjs/openai",
-  "version": "13.30.0",
+  "version": "13.32.0",
   "peerDependencies": {
-    "@dereekb/date": "13.30.0",
-    "@dereekb/model": "13.30.0",
-    "@dereekb/nestjs": "13.30.0",
-    "@dereekb/rxjs": "13.30.0",
-    "@dereekb/util": "13.30.0",
+    "@dereekb/date": "13.32.0",
+    "@dereekb/model": "13.32.0",
+    "@dereekb/nestjs": "13.32.0",
+    "@dereekb/rxjs": "13.32.0",
+    "@dereekb/util": "13.32.0",
     "@nestjs/common": "^11.1.19",
     "@nestjs/config": "^4.0.4",
     "express": "^5.2.1",

package/openrouter/package.json

@@ -1,9 +1,9 @@
 {
   "name": "@dereekb/nestjs/openrouter",
-  "version": "13.30.0",
+  "version": "13.32.0",
   "peerDependencies": {
-    "@dereekb/util": "13.30.0",
-    "@dereekb/nestjs": "13.30.0",
+    "@dereekb/util": "13.32.0",
+    "@dereekb/nestjs": "13.32.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.30.0",
+  "version": "13.32.0",
   "types": "./src/index.d.ts",
   "module": "./index.esm.js",
   "main": "./index.cjs.js",
@@ -68,8 +68,8 @@
     }
   },
   "peerDependencies": {
-    "@dereekb/rxjs": "13.30.0",
-    "@dereekb/util": "13.30.0",
+    "@dereekb/rxjs": "13.32.0",
+    "@dereekb/util": "13.32.0",
     "@nestjs/common": "^11.1.19",
     "@nestjs/config": "^4.0.4",
     "@typeform/api-client": "^2.10.2",

package/stripe/package.json

@@ -1,12 +1,12 @@
 {
   "name": "@dereekb/nestjs/stripe",
-  "version": "13.30.0",
+  "version": "13.32.0",
   "peerDependencies": {
-    "@dereekb/date": "13.30.0",
-    "@dereekb/model": "13.30.0",
-    "@dereekb/nestjs": "13.30.0",
-    "@dereekb/rxjs": "13.30.0",
-    "@dereekb/util": "13.30.0",
+    "@dereekb/date": "13.32.0",
+    "@dereekb/model": "13.32.0",
+    "@dereekb/nestjs": "13.32.0",
+    "@dereekb/rxjs": "13.32.0",
+    "@dereekb/util": "13.32.0",
     "@nestjs/common": "^11.1.19",
     "@nestjs/config": "^4.0.4",
     "express": "^5.2.1",

package/twilio/package.json

@@ -1,12 +1,12 @@
 {
   "name": "@dereekb/nestjs/twilio",
-  "version": "13.30.0",
+  "version": "13.32.0",
   "peerDependencies": {
-    "@dereekb/date": "13.30.0",
-    "@dereekb/model": "13.30.0",
-    "@dereekb/nestjs": "13.30.0",
-    "@dereekb/rxjs": "13.30.0",
-    "@dereekb/util": "13.30.0",
+    "@dereekb/date": "13.32.0",
+    "@dereekb/model": "13.32.0",
+    "@dereekb/nestjs": "13.32.0",
+    "@dereekb/rxjs": "13.32.0",
+    "@dereekb/util": "13.32.0",
     "@nestjs/common": "^11.1.19",
     "@nestjs/config": "^4.0.4",
     "express": "^5.2.1",

package/typeform/package.json

@@ -1,12 +1,12 @@
 {
   "name": "@dereekb/nestjs/typeform",
-  "version": "13.30.0",
+  "version": "13.32.0",
   "peerDependencies": {
-    "@dereekb/date": "13.30.0",
-    "@dereekb/model": "13.30.0",
-    "@dereekb/nestjs": "13.30.0",
-    "@dereekb/rxjs": "13.30.0",
-    "@dereekb/util": "13.30.0",
+    "@dereekb/date": "13.32.0",
+    "@dereekb/model": "13.32.0",
+    "@dereekb/nestjs": "13.32.0",
+    "@dereekb/rxjs": "13.32.0",
+    "@dereekb/util": "13.32.0",
     "@nestjs/common": "^11.1.19",
     "@nestjs/config": "^4.0.4",
     "@typeform/api-client": "^2.10.2",

package/vapiai/package.json

@@ -1,12 +1,12 @@
 {
   "name": "@dereekb/nestjs/vapiai",
-  "version": "13.30.0",
+  "version": "13.32.0",
   "peerDependencies": {
-    "@dereekb/date": "13.30.0",
-    "@dereekb/model": "13.30.0",
-    "@dereekb/nestjs": "13.30.0",
-    "@dereekb/rxjs": "13.30.0",
-    "@dereekb/util": "13.30.0",
+    "@dereekb/date": "13.32.0",
+    "@dereekb/model": "13.32.0",
+    "@dereekb/nestjs": "13.32.0",
+    "@dereekb/rxjs": "13.32.0",
+    "@dereekb/util": "13.32.0",
     "@nestjs/common": "^11.1.19",
     "@nestjs/config": "^4.0.4",
     "@vapi-ai/server-sdk": "^0.11.0",