blendsdk 5.33.0

package/dist/webafx-mailer/mail-plugin.js

@@ -0,0 +1,155 @@
+/**
+ * WebAFX plugin integration for mail providers.
+ *
+ * Provides convenience factory functions that wire a MailProvider instance
+ * into a WebAFX application as a singleton service with health check and
+ * graceful shutdown support.
+ *
+ * This is the ONLY file in @blendsdk/webafx-mailer that imports from @blendsdk/webafx,
+ * which is why webafx is an optional peer dependency (not a hard dependency).
+ *
+ * The design mirrors @blendsdk/webafx-cache's cache-plugin.ts exactly.
+ *
+ * @packageDocumentation
+ */
+import { MemoryMailProvider } from "./memory-mail-provider.js";
+import { SmtpMailProvider } from "./smtp-mail-provider.js";
+// ---------------------------------------------------------------------------
+// Default Constants
+// ---------------------------------------------------------------------------
+/** Default plugin priority — installs after most core plugins */
+const DEFAULT_PLUGIN_PRIORITY = 30;
+// ---------------------------------------------------------------------------
+// Plugin Factory Functions
+// ---------------------------------------------------------------------------
+/**
+ * Create a WebAFX PluginDefinition from any MailProvider instance.
+ *
+ * This is the core function that wires a mail provider into WebAFX:
+ * 1. Registers the provider as a singleton service in the service container
+ * 2. Hooks the provider's health() into the /health endpoint
+ * 3. Hooks the provider's shutdown() into graceful shutdown
+ *
+ * The service name is read from `provider.serviceName` (defaults to "mailer").
+ *
+ * @param provider - Any MailProvider instance (SMTP, Memory, or custom)
+ * @param options - Optional overrides for plugin priority
+ * @returns A WebAFX PluginDefinition ready to pass to app.use()
+ *
+ * @example
+ * ```typescript
+ * const mailer = new SmtpMailProvider({ host: "smtp.example.com", port: 587 });
+ * app.use(createMailPlugin(mailer));
+ * ```
+ */
+export function createMailPlugin(provider, options) {
+    return {
+        name: provider.serviceName,
+        priority: options?.priority ?? DEFAULT_PLUGIN_PRIORITY,
+        factory: async ({ app, logger }) => {
+            // Register the mail provider as an application-wide singleton service.
+            // The factory ignores container/settings since the provider is pre-created.
+            app.registerService({
+                name: provider.serviceName,
+                type: "singleton",
+                factory: () => provider,
+                dispose: async () => {
+                    await provider.shutdown();
+                },
+            });
+            await logger.info(`Mail plugin "${provider.serviceName}" initialized ` +
+                `(${provider.constructor.name})`);
+            // Return Plugin hooks for health monitoring and graceful shutdown
+            return {
+                health: () => provider.health(),
+                shutdown: () => provider.shutdown(),
+            };
+        },
+    };
+}
+/**
+ * Create a WebAFX mail plugin with an SMTP backend. One-liner registration.
+ *
+ * Creates a SmtpMailProvider internally and returns a PluginDefinition.
+ * The user never needs to instantiate the provider manually.
+ *
+ * @param config - SMTP configuration (host, port, auth, TLS options)
+ * @returns A WebAFX PluginDefinition ready to pass to app.use()
+ *
+ * @example
+ * ```typescript
+ * app.use(smtpMailPlugin({
+ *     host: "smtp.example.com",
+ *     port: 587,
+ *     secure: false,
+ *     auth: { user: "user@example.com", pass: "secret" },
+ * }));
+ * ```
+ */
+export function smtpMailPlugin(config) {
+    const provider = new SmtpMailProvider(config);
+    return createMailPlugin(provider);
+}
+/**
+ * Create a WebAFX mail plugin with an In-Memory backend. One-liner registration.
+ *
+ * Creates a MemoryMailProvider internally and returns a PluginDefinition.
+ * Ideal for development and testing — no emails are actually sent.
+ *
+ * @param config - Optional memory configuration (serviceName override)
+ * @returns A WebAFX PluginDefinition ready to pass to app.use()
+ *
+ * @example
+ * ```typescript
+ * app.use(memoryMailPlugin());
+ * ```
+ */
+export function memoryMailPlugin(config) {
+    const provider = new MemoryMailProvider(config);
+    return createMailPlugin(provider);
+}
+/**
+ * Create a MailProvider based on configuration type.
+ *
+ * Factory function for environment-based backend switching.
+ * Returns the appropriate provider based on `config.type`.
+ * Use with `createMailPlugin()` to register in WebAFX.
+ *
+ * @param config - Mail factory configuration with type discriminator
+ * @returns A MailProvider instance (SMTP or Memory)
+ * @throws Error if config.type is not "smtp" or "memory"
+ *
+ * @example
+ * ```typescript
+ * const mailer = createMailProvider({
+ *     type: process.env.NODE_ENV === "production" ? "smtp" : "memory",
+ *     host: process.env.SMTP_HOST,
+ *     port: Number(process.env.SMTP_PORT || 587),
+ * });
+ * app.use(createMailPlugin(mailer));
+ * ```
+ */
+export function createMailProvider(config) {
+    switch (config.type) {
+        case "smtp":
+            return new SmtpMailProvider({
+                serviceName: config.serviceName,
+                host: config.host,
+                port: config.port,
+                secure: config.secure,
+                auth: config.auth,
+                tls: config.tls,
+            });
+        case "memory":
+            return new MemoryMailProvider({
+                serviceName: config.serviceName,
+            });
+        default: {
+            // Exhaustive check — provides a clear runtime error if called with
+            // an invalid type that TypeScript couldn't catch at compile time
+            const unknownType = config.type;
+            throw new Error(`Unknown mail type: "${unknownType}". Supported types: "smtp", "memory".`);
+        }
+    }
+}
+//# sourceMappingURL=mail-plugin.js.map

package/dist/webafx-mailer/mail-plugin.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"mail-plugin.js","sourceRoot":"","sources":["../src/mail-plugin.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAKH,OAAO,EAAE,kBAAkB,EAAE,MAAM,2BAA2B,CAAC;AAC/D,OAAO,EAAE,gBAAgB,EAAE,MAAM,yBAAyB,CAAC;AAG3D,8EAA8E;AAC9E,oBAAoB;AACpB,8EAA8E;AAE9E,iEAAiE;AACjE,MAAM,uBAAuB,GAAG,EAAE,CAAC;AAEnC,8EAA8E;AAC9E,2BAA2B;AAC3B,8EAA8E;AAE9E;;;;;;;;;;;;;;;;;;;GAmBG;AACH,MAAM,UAAU,gBAAgB,CAC5B,QAAsB,EACtB,OAA+B;IAE/B,OAAO;QACH,IAAI,EAAE,QAAQ,CAAC,WAAW;QAC1B,QAAQ,EAAE,OAAO,EAAE,QAAQ,IAAI,uBAAuB;QAEtD,OAAO,EAAE,KAAK,EAAE,EAAE,GAAG,EAAE,MAAM,EAAE,EAAE,EAAE;YAC/B,uEAAuE;YACvE,4EAA4E;YAC5E,GAAG,CAAC,eAAe,CAAC;gBAChB,IAAI,EAAE,QAAQ,CAAC,WAAW;gBAC1B,IAAI,EAAE,WAAW;gBACjB,OAAO,EAAE,GAAG,EAAE,CAAC,QAAQ;gBACvB,OAAO,EAAE,KAAK,IAAI,EAAE;oBAChB,MAAM,QAAQ,CAAC,QAAQ,EAAE,CAAC;gBAC9B,CAAC;aACJ,CAAC,CAAC;YAEH,MAAM,MAAM,CAAC,IAAI,CACb,gBAAgB,QAAQ,CAAC,WAAW,gBAAgB;gBAChD,IAAI,QAAQ,CAAC,WAAW,CAAC,IAAI,GAAG,CACvC,CAAC;YAEF,kEAAkE;YAClE,OAAO;gBACH,MAAM,EAAE,GAAG,EAAE,CAAC,QAAQ,CAAC,MAAM,EAAE;gBAC/B,QAAQ,EAAE,GAAG,EAAE,CAAC,QAAQ,CAAC,QAAQ,EAAE;aACtC,CAAC;QACN,CAAC;KACJ,CAAC;AACN,CAAC;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,MAAM,UAAU,cAAc,CAAC,MAAsB;IACjD,MAAM,QAAQ,GAAG,IAAI,gBAAgB,CAAC,MAAM,CAAC,CAAC;IAC9C,OAAO,gBAAgB,CAAC,QAAQ,CAAC,CAAC;AACtC,CAAC;AAED;;;;;;;;;;;;;GAaG;AACH,MAAM,UAAU,gBAAgB,CAAC,MAAyB;IACtD,MAAM,QAAQ,GAAG,IAAI,kBAAkB,CAAC,MAAM,CAAC,CAAC;IAChD,OAAO,gBAAgB,CAAC,QAAQ,CAAC,CAAC;AACtC,CAAC;AAED;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,MAAM,UAAU,kBAAkB,CAAC,MAAyB;IACxD,QAAQ,MAAM,CAAC,IAAI,EAAE,CAAC;QAClB,KAAK,MAAM;YACP,OAAO,IAAI,gBAAgB,CAAC;gBACxB,WAAW,EAAE,MAAM,CAAC,WAAW;gBAC/B,IAAI,EAAE,MAAM,CAAC,IAAK;gBAClB,IAAI,EAAE,MAAM,CAAC,IAAK;gBAClB,MAAM,EAAE,MAAM,CAAC,MAAM;gBACrB,IAAI,EAAE,MAAM,CAAC,IAAI;gBACjB,GAAG,EAAE,MAAM,CAAC,GAAG;aAClB,CAAC,CAAC;QAEP,KAAK,QAAQ;YACT,OAAO,IAAI,kBAAkB,CAAC;gBAC1B,WAAW,EAAE,MAAM,CAAC,WAAW;aAClC,CAAC,CAAC;QAEP,OAAO,CAAC,CAAC,CAAC;YACN,mEAAmE;YACnE,iEAAiE;YACjE,MAAM,WAAW,GAAI,MAA2B,CAAC,IAAI,CAAC;YACtD,MAAM,IAAI,KAAK,CACX,uBAAuB,WAAW,uCAAuC,CAC5E,CAAC;QACN,CAAC;IACL,CAAC;AACL,CAAC"}

package/dist/webafx-mailer/memory-mail-provider.d.ts

@@ -0,0 +1,85 @@
+/**
+ * In-memory mail provider for testing.
+ *
+ * Stores all sent messages in an array that can be queried for test assertions.
+ * Does not actually send any emails — purely for development and testing use.
+ *
+ * Provides helper methods for test assertions:
+ * - `getSentMessages()` — returns all sent messages (as a copy)
+ * - `getLastMessage()` — returns the most recently sent message
+ * - `clear()` — empties the stored messages
+ *
+ * @example
+ * ```typescript
+ * const mailer = new MemoryMailProvider();
+ * await mailer.send({ from: "a@b.com", to: "c@d.com", subject: "Hi", text: "Hello" });
+ *
+ * const sent = mailer.getSentMessages();
+ * expect(sent).toHaveLength(1);
+ * expect(sent[0].message.subject).toBe("Hi");
+ * ```
+ */
+import { MailProvider } from "./abstract-mail-provider.js";
+import type { MailMessage, MailResult, MemoryMailConfig } from "./types.js";
+/** Stored message entry — includes both the original message and send result */
+export interface SentMailEntry {
+    /** The original mail message as submitted to send() */
+    message: MailMessage;
+    /** The result returned from send() */
+    result: MailResult;
+}
+export declare class MemoryMailProvider extends MailProvider {
+    /** Internal store of all sent messages */
+    protected messages: SentMailEntry[];
+    /**
+     * Create a new in-memory mail provider.
+     *
+     * @param config - Optional config; defaults to `{ serviceName: "mailer" }`
+     */
+    constructor(config?: MemoryMailConfig);
+    /**
+     * "Send" an email by storing it in memory.
+     *
+     * All recipients (to, cc, bcc) are marked as accepted.
+     * A deterministic messageId is generated for test predictability.
+     *
+     * @param message - The email message to store
+     * @returns Result with all recipients in accepted list
+     */
+    send(message: MailMessage): Promise<MailResult>;
+    /**
+     * Get all sent messages (for test assertions).
+     *
+     * Returns a shallow copy of the internal array to prevent
+     * external mutation of the stored data.
+     *
+     * @returns Array of all sent message entries (message + result)
+     */
+    getSentMessages(): SentMailEntry[];
+    /**
+     * Get the last sent message (convenience for single-email tests).
+     *
+     * @returns The most recently sent entry, or undefined if no messages sent
+     */
+    getLastMessage(): SentMailEntry | undefined;
+    /**
+     * Clear all stored messages.
+     *
+     * Useful for resetting state between test cases.
+     */
+    clear(): void;
+    /**
+     * Health check — always returns true.
+     *
+     * The memory provider has no external dependencies,
+     * so it's always "healthy".
+     */
+    health(): Promise<boolean>;
+    /**
+     * Graceful shutdown — clears all stored messages.
+     *
+     * Releases the in-memory message store.
+     */
+    shutdown(): Promise<void>;
+}
+//# sourceMappingURL=memory-mail-provider.d.ts.map

package/dist/webafx-mailer/memory-mail-provider.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"memory-mail-provider.d.ts","sourceRoot":"","sources":["../src/memory-mail-provider.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAEH,OAAO,EAAE,YAAY,EAAE,MAAM,6BAA6B,CAAC;AAC3D,OAAO,KAAK,EAAE,WAAW,EAAE,UAAU,EAAE,gBAAgB,EAAE,MAAM,YAAY,CAAC;AAE5E,gFAAgF;AAChF,MAAM,WAAW,aAAa;IAC1B,uDAAuD;IACvD,OAAO,EAAE,WAAW,CAAC;IACrB,sCAAsC;IACtC,MAAM,EAAE,UAAU,CAAC;CACtB;AAED,qBAAa,kBAAmB,SAAQ,YAAY;IAChD,0CAA0C;IAC1C,SAAS,CAAC,QAAQ,EAAE,aAAa,EAAE,CAAM;IAEzC;;;;OAIG;gBACS,MAAM,CAAC,EAAE,gBAAgB;IAIrC;;;;;;;;OAQG;IACG,IAAI,CAAC,OAAO,EAAE,WAAW,GAAG,OAAO,CAAC,UAAU,CAAC;IAwBrD;;;;;;;OAOG;IACH,eAAe,IAAI,aAAa,EAAE;IAIlC;;;;OAIG;IACH,cAAc,IAAI,aAAa,GAAG,SAAS;IAM3C;;;;OAIG;IACH,KAAK,IAAI,IAAI;IAIb;;;;;OAKG;IACG,MAAM,IAAI,OAAO,CAAC,OAAO,CAAC;IAIhC;;;;OAIG;IACG,QAAQ,IAAI,OAAO,CAAC,IAAI,CAAC;CAGlC"}

package/dist/webafx-mailer/memory-mail-provider.js

@@ -0,0 +1,111 @@
+/**
+ * In-memory mail provider for testing.
+ *
+ * Stores all sent messages in an array that can be queried for test assertions.
+ * Does not actually send any emails — purely for development and testing use.
+ *
+ * Provides helper methods for test assertions:
+ * - `getSentMessages()` — returns all sent messages (as a copy)
+ * - `getLastMessage()` — returns the most recently sent message
+ * - `clear()` — empties the stored messages
+ *
+ * @example
+ * ```typescript
+ * const mailer = new MemoryMailProvider();
+ * await mailer.send({ from: "a@b.com", to: "c@d.com", subject: "Hi", text: "Hello" });
+ *
+ * const sent = mailer.getSentMessages();
+ * expect(sent).toHaveLength(1);
+ * expect(sent[0].message.subject).toBe("Hi");
+ * ```
+ */
+import { MailProvider } from "./abstract-mail-provider.js";
+export class MemoryMailProvider extends MailProvider {
+    /** Internal store of all sent messages */
+    messages = [];
+    /**
+     * Create a new in-memory mail provider.
+     *
+     * @param config - Optional config; defaults to `{ serviceName: "mailer" }`
+     */
+    constructor(config) {
+        super(config ?? {});
+    }
+    /**
+     * "Send" an email by storing it in memory.
+     *
+     * All recipients (to, cc, bcc) are marked as accepted.
+     * A deterministic messageId is generated for test predictability.
+     *
+     * @param message - The email message to store
+     * @returns Result with all recipients in accepted list
+     */
+    async send(message) {
+        // Normalize all recipient fields to arrays for consistent result format
+        const toArray = Array.isArray(message.to) ? message.to : [message.to];
+        const ccArray = message.cc
+            ? Array.isArray(message.cc)
+                ? message.cc
+                : [message.cc]
+            : [];
+        const bccArray = message.bcc
+            ? Array.isArray(message.bcc)
+                ? message.bcc
+                : [message.bcc]
+            : [];
+        const result = {
+            accepted: [...toArray, ...ccArray, ...bccArray],
+            rejected: [],
+            messageId: `<memory-${Date.now()}-${this.messages.length}@test>`,
+        };
+        this.messages.push({ message, result });
+        return result;
+    }
+    /**
+     * Get all sent messages (for test assertions).
+     *
+     * Returns a shallow copy of the internal array to prevent
+     * external mutation of the stored data.
+     *
+     * @returns Array of all sent message entries (message + result)
+     */
+    getSentMessages() {
+        return [...this.messages];
+    }
+    /**
+     * Get the last sent message (convenience for single-email tests).
+     *
+     * @returns The most recently sent entry, or undefined if no messages sent
+     */
+    getLastMessage() {
+        return this.messages.length > 0
+            ? this.messages[this.messages.length - 1]
+            : undefined;
+    }
+    /**
+     * Clear all stored messages.
+     *
+     * Useful for resetting state between test cases.
+     */
+    clear() {
+        this.messages = [];
+    }
+    /**
+     * Health check — always returns true.
+     *
+     * The memory provider has no external dependencies,
+     * so it's always "healthy".
+     */
+    async health() {
+        return true;
+    }
+    /**
+     * Graceful shutdown — clears all stored messages.
+     *
+     * Releases the in-memory message store.
+     */
+    async shutdown() {
+        this.clear();
+    }
+}
+//# sourceMappingURL=memory-mail-provider.js.map

package/dist/webafx-mailer/memory-mail-provider.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"memory-mail-provider.js","sourceRoot":"","sources":["../src/memory-mail-provider.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAEH,OAAO,EAAE,YAAY,EAAE,MAAM,6BAA6B,CAAC;AAW3D,MAAM,OAAO,kBAAmB,SAAQ,YAAY;IAChD,0CAA0C;IAChC,QAAQ,GAAoB,EAAE,CAAC;IAEzC;;;;OAIG;IACH,YAAY,MAAyB;QACjC,KAAK,CAAC,MAAM,IAAI,EAAE,CAAC,CAAC;IACxB,CAAC;IAED;;;;;;;;OAQG;IACH,KAAK,CAAC,IAAI,CAAC,OAAoB;QAC3B,wEAAwE;QACxE,MAAM,OAAO,GAAG,KAAK,CAAC,OAAO,CAAC,OAAO,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,EAAE,CAAC,CAAC;QACtE,MAAM,OAAO,GAAG,OAAO,CAAC,EAAE;YACtB,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,OAAO,CAAC,EAAE,CAAC;gBACvB,CAAC,CAAC,OAAO,CAAC,EAAE;gBACZ,CAAC,CAAC,CAAC,OAAO,CAAC,EAAE,CAAC;YAClB,CAAC,CAAC,EAAE,CAAC;QACT,MAAM,QAAQ,GAAG,OAAO,CAAC,GAAG;YACxB,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,OAAO,CAAC,GAAG,CAAC;gBACxB,CAAC,CAAC,OAAO,CAAC,GAAG;gBACb,CAAC,CAAC,CAAC,OAAO,CAAC,GAAG,CAAC;YACnB,CAAC,CAAC,EAAE,CAAC;QAET,MAAM,MAAM,GAAe;YACvB,QAAQ,EAAE,CAAC,GAAG,OAAO,EAAE,GAAG,OAAO,EAAE,GAAG,QAAQ,CAAC;YAC/C,QAAQ,EAAE,EAAE;YACZ,SAAS,EAAE,WAAW,IAAI,CAAC,GAAG,EAAE,IAAI,IAAI,CAAC,QAAQ,CAAC,MAAM,QAAQ;SACnE,CAAC;QAEF,IAAI,CAAC,QAAQ,CAAC,IAAI,CAAC,EAAE,OAAO,EAAE,MAAM,EAAE,CAAC,CAAC;QACxC,OAAO,MAAM,CAAC;IAClB,CAAC;IAED;;;;;;;OAOG;IACH,eAAe;QACX,OAAO,CAAC,GAAG,IAAI,CAAC,QAAQ,CAAC,CAAC;IAC9B,CAAC;IAED;;;;OAIG;IACH,cAAc;QACV,OAAO,IAAI,CAAC,QAAQ,CAAC,MAAM,GAAG,CAAC;YAC3B,CAAC,CAAC,IAAI,CAAC,QAAQ,CAAC,IAAI,CAAC,QAAQ,CAAC,MAAM,GAAG,CAAC,CAAC;YACzC,CAAC,CAAC,SAAS,CAAC;IACpB,CAAC;IAED;;;;OAIG;IACH,KAAK;QACD,IAAI,CAAC,QAAQ,GAAG,EAAE,CAAC;IACvB,CAAC;IAED;;;;;OAKG;IACH,KAAK,CAAC,MAAM;QACR,OAAO,IAAI,CAAC;IAChB,CAAC;IAED;;;;OAIG;IACH,KAAK,CAAC,QAAQ;QACV,IAAI,CAAC,KAAK,EAAE,CAAC;IACjB,CAAC;CACJ"}

package/dist/webafx-mailer/smtp-mail-provider.d.ts

@@ -0,0 +1,65 @@
+/**
+ * SMTP mail provider using nodemailer.
+ *
+ * Wraps nodemailer's transport to provide a clean MailProvider interface
+ * with health check and graceful shutdown support. The underlying transport
+ * handles connection pooling internally.
+ *
+ * Key design decisions vs. v3:
+ * - `secure` defaults to false (modern SMTP uses STARTTLS on port 587)
+ * - No hardcoded `tls.rejectUnauthorized: false` — configurable via `tls` option
+ * - `transporter.verify()` for health check — tests SMTP connection without sending
+ * - `transporter.close()` for graceful shutdown — closes the connection pool
+ *
+ * @example
+ * ```typescript
+ * const mailer = new SmtpMailProvider({
+ *     host: "smtp.example.com",
+ *     port: 587,
+ *     secure: false,
+ *     auth: { user: "user@example.com", pass: "secret" },
+ * });
+ * await mailer.send({ from: "a@b.com", to: "c@d.com", subject: "Hi", text: "Hello" });
+ * ```
+ */
+import nodemailer from "nodemailer";
+import { MailProvider } from "./abstract-mail-provider.js";
+import type { MailMessage, MailResult, SmtpMailConfig } from "./types.js";
+export declare class SmtpMailProvider extends MailProvider {
+    /** Nodemailer transport instance — handles SMTP connection pooling */
+    protected transporter: nodemailer.Transporter;
+    /**
+     * Create a new SMTP mail provider.
+     *
+     * @param config - SMTP connection settings (host, port, auth, TLS options)
+     */
+    constructor(config: SmtpMailConfig);
+    /**
+     * Send an email via SMTP.
+     *
+     * Converts our MailMessage to nodemailer's format and sends it.
+     * Array recipients are joined with commas as nodemailer expects.
+     *
+     * @param message - The email message to send
+     * @returns Result with accepted/rejected addresses and message ID
+     * @throws Error on SMTP connection failure, auth failure, or send rejection
+     */
+    send(message: MailMessage): Promise<MailResult>;
+    /**
+     * Health check — verifies the SMTP connection is alive.
+     *
+     * Uses nodemailer's `verify()` which performs an EHLO/HELO handshake
+     * with the server without sending any email.
+     *
+     * @returns true if SMTP server is reachable and accepts connections
+     */
+    health(): Promise<boolean>;
+    /**
+     * Graceful shutdown — closes the nodemailer transport.
+     *
+     * Releases the underlying TCP connection pool. After calling this,
+     * subsequent `send()` calls will fail.
+     */
+    shutdown(): Promise<void>;
+}
+//# sourceMappingURL=smtp-mail-provider.d.ts.map

package/dist/webafx-mailer/smtp-mail-provider.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"smtp-mail-provider.d.ts","sourceRoot":"","sources":["../src/smtp-mail-provider.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AAEH,OAAO,UAAU,MAAM,YAAY,CAAC;AAEpC,OAAO,EAAE,YAAY,EAAE,MAAM,6BAA6B,CAAC;AAC3D,OAAO,KAAK,EAAE,WAAW,EAAE,UAAU,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC;AAE1E,qBAAa,gBAAiB,SAAQ,YAAY;IAC9C,sEAAsE;IACtE,SAAS,CAAC,WAAW,EAAE,UAAU,CAAC,WAAW,CAAC;IAE9C;;;;OAIG;gBACS,MAAM,EAAE,cAAc;IAclC;;;;;;;;;OASG;IACG,IAAI,CAAC,OAAO,EAAE,WAAW,GAAG,OAAO,CAAC,UAAU,CAAC;IA+BrD;;;;;;;OAOG;IACG,MAAM,IAAI,OAAO,CAAC,OAAO,CAAC;IAShC;;;;;OAKG;IACG,QAAQ,IAAI,OAAO,CAAC,IAAI,CAAC;CAGlC"}

package/dist/webafx-mailer/smtp-mail-provider.js

@@ -0,0 +1,113 @@
+/**
+ * SMTP mail provider using nodemailer.
+ *
+ * Wraps nodemailer's transport to provide a clean MailProvider interface
+ * with health check and graceful shutdown support. The underlying transport
+ * handles connection pooling internally.
+ *
+ * Key design decisions vs. v3:
+ * - `secure` defaults to false (modern SMTP uses STARTTLS on port 587)
+ * - No hardcoded `tls.rejectUnauthorized: false` — configurable via `tls` option
+ * - `transporter.verify()` for health check — tests SMTP connection without sending
+ * - `transporter.close()` for graceful shutdown — closes the connection pool
+ *
+ * @example
+ * ```typescript
+ * const mailer = new SmtpMailProvider({
+ *     host: "smtp.example.com",
+ *     port: 587,
+ *     secure: false,
+ *     auth: { user: "user@example.com", pass: "secret" },
+ * });
+ * await mailer.send({ from: "a@b.com", to: "c@d.com", subject: "Hi", text: "Hello" });
+ * ```
+ */
+import nodemailer from "nodemailer";
+import { MailProvider } from "./abstract-mail-provider.js";
+export class SmtpMailProvider extends MailProvider {
+    /** Nodemailer transport instance — handles SMTP connection pooling */
+    transporter;
+    /**
+     * Create a new SMTP mail provider.
+     *
+     * @param config - SMTP connection settings (host, port, auth, TLS options)
+     */
+    constructor(config) {
+        super(config);
+        // Create nodemailer transport with provided SMTP settings.
+        // secure defaults to false — most modern SMTP servers use STARTTLS on port 587.
+        this.transporter = nodemailer.createTransport({
+            host: config.host,
+            port: config.port,
+            secure: config.secure ?? false,
+            auth: config.auth,
+            tls: config.tls,
+        });
+    }
+    /**
+     * Send an email via SMTP.
+     *
+     * Converts our MailMessage to nodemailer's format and sends it.
+     * Array recipients are joined with commas as nodemailer expects.
+     *
+     * @param message - The email message to send
+     * @returns Result with accepted/rejected addresses and message ID
+     * @throws Error on SMTP connection failure, auth failure, or send rejection
+     */
+    async send(message) {
+        const info = await this.transporter.sendMail({
+            from: message.from,
+            to: Array.isArray(message.to) ? message.to.join(", ") : message.to,
+            cc: message.cc
+                ? Array.isArray(message.cc)
+                    ? message.cc.join(", ")
+                    : message.cc
+                : undefined,
+            bcc: message.bcc
+                ? Array.isArray(message.bcc)
+                    ? message.bcc.join(", ")
+                    : message.bcc
+                : undefined,
+            subject: message.subject,
+            text: message.text,
+            html: message.html,
+            attachments: message.attachments?.map((a) => ({
+                filename: a.filename,
+                content: a.content,
+                contentType: a.contentType,
+            })),
+        });
+        return {
+            accepted: Array.isArray(info.accepted) ? info.accepted.map(String) : [],
+            rejected: Array.isArray(info.rejected) ? info.rejected.map(String) : [],
+            messageId: info.messageId,
+        };
+    }
+    /**
+     * Health check — verifies the SMTP connection is alive.
+     *
+     * Uses nodemailer's `verify()` which performs an EHLO/HELO handshake
+     * with the server without sending any email.
+     *
+     * @returns true if SMTP server is reachable and accepts connections
+     */
+    async health() {
+        try {
+            await this.transporter.verify();
+            return true;
+        }
+        catch {
+            return false;
+        }
+    }
+    /**
+     * Graceful shutdown — closes the nodemailer transport.
+     *
+     * Releases the underlying TCP connection pool. After calling this,
+     * subsequent `send()` calls will fail.
+     */
+    async shutdown() {
+        this.transporter.close();
+    }
+}
+//# sourceMappingURL=smtp-mail-provider.js.map

package/dist/webafx-mailer/smtp-mail-provider.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"smtp-mail-provider.js","sourceRoot":"","sources":["../src/smtp-mail-provider.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AAEH,OAAO,UAAU,MAAM,YAAY,CAAC;AAEpC,OAAO,EAAE,YAAY,EAAE,MAAM,6BAA6B,CAAC;AAG3D,MAAM,OAAO,gBAAiB,SAAQ,YAAY;IAC9C,sEAAsE;IAC5D,WAAW,CAAyB;IAE9C;;;;OAIG;IACH,YAAY,MAAsB;QAC9B,KAAK,CAAC,MAAM,CAAC,CAAC;QAEd,2DAA2D;QAC3D,gFAAgF;QAChF,IAAI,CAAC,WAAW,GAAG,UAAU,CAAC,eAAe,CAAC;YAC1C,IAAI,EAAE,MAAM,CAAC,IAAI;YACjB,IAAI,EAAE,MAAM,CAAC,IAAI;YACjB,MAAM,EAAE,MAAM,CAAC,MAAM,IAAI,KAAK;YAC9B,IAAI,EAAE,MAAM,CAAC,IAAI;YACjB,GAAG,EAAE,MAAM,CAAC,GAAG;SAClB,CAAC,CAAC;IACP,CAAC;IAED;;;;;;;;;OASG;IACH,KAAK,CAAC,IAAI,CAAC,OAAoB;QAC3B,MAAM,IAAI,GAAG,MAAM,IAAI,CAAC,WAAW,CAAC,QAAQ,CAAC;YACzC,IAAI,EAAE,OAAO,CAAC,IAAI;YAClB,EAAE,EAAE,KAAK,CAAC,OAAO,CAAC,OAAO,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,EAAE,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,EAAE;YAClE,EAAE,EAAE,OAAO,CAAC,EAAE;gBACV,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,OAAO,CAAC,EAAE,CAAC;oBACvB,CAAC,CAAC,OAAO,CAAC,EAAE,CAAC,IAAI,CAAC,IAAI,CAAC;oBACvB,CAAC,CAAC,OAAO,CAAC,EAAE;gBAChB,CAAC,CAAC,SAAS;YACf,GAAG,EAAE,OAAO,CAAC,GAAG;gBACZ,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,OAAO,CAAC,GAAG,CAAC;oBACxB,CAAC,CAAC,OAAO,CAAC,GAAG,CAAC,IAAI,CAAC,IAAI,CAAC;oBACxB,CAAC,CAAC,OAAO,CAAC,GAAG;gBACjB,CAAC,CAAC,SAAS;YACf,OAAO,EAAE,OAAO,CAAC,OAAO;YACxB,IAAI,EAAE,OAAO,CAAC,IAAI;YAClB,IAAI,EAAE,OAAO,CAAC,IAAI;YAClB,WAAW,EAAE,OAAO,CAAC,WAAW,EAAE,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC;gBAC1C,QAAQ,EAAE,CAAC,CAAC,QAAQ;gBACpB,OAAO,EAAE,CAAC,CAAC,OAAO;gBAClB,WAAW,EAAE,CAAC,CAAC,WAAW;aAC7B,CAAC,CAAC;SACN,CAAC,CAAC;QAEH,OAAO;YACH,QAAQ,EAAE,KAAK,CAAC,OAAO,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,EAAE;YACvE,QAAQ,EAAE,KAAK,CAAC,OAAO,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,EAAE;YACvE,SAAS,EAAE,IAAI,CAAC,SAAS;SAC5B,CAAC;IACN,CAAC;IAED;;;;;;;OAOG;IACH,KAAK,CAAC,MAAM;QACR,IAAI,CAAC;YACD,MAAM,IAAI,CAAC,WAAW,CAAC,MAAM,EAAE,CAAC;YAChC,OAAO,IAAI,CAAC;QAChB,CAAC;QAAC,MAAM,CAAC;YACL,OAAO,KAAK,CAAC;QACjB,CAAC;IACL,CAAC;IAED;;;;;OAKG;IACH,KAAK,CAAC,QAAQ;QACV,IAAI,CAAC,WAAW,CAAC,KAAK,EAAE,CAAC;IAC7B,CAAC;CACJ"}