@veap/mail 0.1.0 → 0.1.1

package/README.md

@@ -1,5 +1,6 @@
-[![CI](https://github.com/veapjs/veap-mail/actions/workflows/ci.yml/badge.svg)](https://github.com/veapjs/veap-mail/actions/workflows/ci.yml)
-[![Release](https://github.com/veapjs/veap-mail/actions/workflows/release.yml/badge.svg)](https://github.com/veapjs/veap-mail/actions/workflows/release.yml)
+[![CI](https://github.com/veapjs/veap-mail/actions/workflows/CI.yml/badge.svg)](https://github.com/veapjs/veap-mail/actions/workflows/CI.yml)
+[![Release](https://github.com/veapjs/veap-mail/actions/workflows/RELEASE.yml/badge.svg)](https://github.com/veapjs/veap-mail/actions/workflows/RELEASE.yml)
+[![Version](https://img.shields.io/npm/v/@veap/mail?style=flat&colorA=000000&colorB=000000)](https://www.npmjs.com/package/@veap/mail)
 
 # @veap/mail
 

package/dist/composition.d.ts

@@ -0,0 +1,63 @@
+/**
+ * Mail configuration options supported in veap.config.ts.
+ */
+export interface MailConfig {
+    /**
+     * Transport driver: "smtp" (default), "console", or "custom".
+     */
+    transport?: "smtp" | "console" | "custom" | string;
+    /**
+     * Nodemailer well-known service (e.g. "gmail", "sendgrid").
+     */
+    service?: string;
+    /**
+     * SMTP server hostname.
+     */
+    host?: string;
+    /**
+     * SMTP server port (e.g. 587, 465, 25, 1025).
+     */
+    port?: number | string;
+    /**
+     * Use TLS/SSL directly (default: true for port 465, false otherwise).
+     */
+    secure?: boolean;
+    /**
+     * Ignore TLS certificate issues (useful for local dev/test servers).
+     */
+    ignoreTLS?: boolean;
+    /**
+     * SMTP authentication username.
+     */
+    username?: string;
+    /**
+     * SMTP authentication password.
+     */
+    password?: string;
+    /**
+     * Default sender address (e.g. "noreply@example.com" or "Acme <noreply@example.com>").
+     */
+    from?: string;
+    /**
+     * Default sender name (e.g. "Acme").
+     */
+    fromName?: string;
+}
+declare module "@veap/kernel" {
+    interface ApplicationBuilder {
+        /**
+         * Registers the communication/mail service provider into the application.
+         */
+        withMail(): this;
+        /**
+         * Alias for `withMail()`.
+         */
+        withCommunication(): this;
+    }
+    interface VeapConfig {
+        /**
+         * Communication and mail transport configuration.
+         */
+        mail?: MailConfig;
+    }
+}

package/dist/composition.js

@@ -0,0 +1,8 @@
+import { ApplicationBuilder } from "@veap/kernel";
+import { CommunicationServiceProvider } from "./provider.js";
+ApplicationBuilder.prototype.withMail = function () {
+    return this.use(CommunicationServiceProvider);
+};
+ApplicationBuilder.prototype.withCommunication = function () {
+    return this.use(CommunicationServiceProvider);
+};

package/dist/context.d.ts

@@ -1,4 +1,4 @@
-import type { IMailer } from "./mailer";
+import type { IMailer } from "./mailer.js";
 /**
  * Typed boundary between the communication use cases and their consumers
  * (facades, application services). The same pattern as

package/dist/index.d.ts

@@ -1,10 +1,11 @@
-export * from "./context";
-export * from "./mail";
-export type { MailMessage as SendMailOptions } from "./mail-message";
-export * from "./mail-message";
-export * from "./mailer";
-export * from "./provider";
-export * from "./providers/console.provider";
-export * from "./providers/nodemailer.provider";
-export { NodemailerMailService as MailService } from "./providers/nodemailer.provider";
-export * from "./translator";
+export * from "./composition.js";
+export * from "./context.js";
+export * from "./mail.js";
+export type { MailMessage as SendMailOptions } from "./mail-message.js";
+export * from "./mail-message.js";
+export * from "./mailer.js";
+export * from "./provider.js";
+export * from "./providers/console.provider.js";
+export * from "./providers/nodemailer.provider.js";
+export { NodemailerMailService as MailService } from "./providers/nodemailer.provider.js";
+export * from "./translator.js";

package/dist/index.js

@@ -1,9 +1,10 @@
-export * from "./context";
-export * from "./mail";
-export * from "./mail-message";
-export * from "./mailer";
-export * from "./provider";
-export * from "./providers/console.provider";
-export * from "./providers/nodemailer.provider";
-export { NodemailerMailService as MailService } from "./providers/nodemailer.provider";
-export * from "./translator";
+export * from "./composition.js";
+export * from "./context.js";
+export * from "./mail.js";
+export * from "./mail-message.js";
+export * from "./mailer.js";
+export * from "./provider.js";
+export * from "./providers/console.provider.js";
+export * from "./providers/nodemailer.provider.js";
+export { NodemailerMailService as MailService } from "./providers/nodemailer.provider.js";
+export * from "./translator.js";

package/dist/mail.d.ts

@@ -1,4 +1,4 @@
-import type { MailMessage } from "./mail-message";
+import type { MailMessage } from "./mail-message.js";
 /**
  * Mailables - the domain vocabulary of email.
  *

package/dist/mail.js

@@ -1,5 +1,5 @@
-import { communicationContext } from "./context";
-import { getMailTranslator } from "./translator";
+import { communicationContext } from "./context.js";
+import { getMailTranslator } from "./translator.js";
 /**
  * Mailables - the domain vocabulary of email.
  *

package/dist/mailer.d.ts

@@ -1,4 +1,5 @@
-import type { MailMessage } from "./mail-message";
+import type { Token } from "@veap/kernel";
+import type { MailMessage } from "./mail-message.js";
 /**
  * Mailer port.
  *
@@ -22,7 +23,11 @@ export interface IMailer {
  * boundaries, the same reason the container keys class tokens with
  * `Symbol.for(...)`.
  */
-export declare const MAILER: unique symbol;
+export declare const MAILER: Token<IMailer>;
+/**
+ * Backward compatibility alias for the mailer port token.
+ */
+export declare const MAIL_SERVICE: Token<IMailer>;
 /**
  * Injection token for a custom transport supplied by the host application.
  *
@@ -30,4 +35,4 @@ export declare const MAILER: unique symbol;
  * this token (e.g. SES, Postmark, Resend, an outbox pattern…) to route all
  * mail through your own delivery system without touching the framework.
  */
-export declare const CUSTOM_MAILER: unique symbol;
+export declare const CUSTOM_MAILER: Token<IMailer>;

package/dist/mailer.js

@@ -6,6 +6,10 @@
  * `Symbol.for(...)`.
  */
 export const MAILER = Symbol.for("veap:communication:mailer");
+/**
+ * Backward compatibility alias for the mailer port token.
+ */
+export const MAIL_SERVICE = MAILER;
 /**
  * Injection token for a custom transport supplied by the host application.
  *

package/dist/provider.d.ts

@@ -6,8 +6,8 @@ import { ServiceProvider } from "@veap/kernel";
  * and binds it into `CommunicationContext`, so facades and services never
  * look transports up themselves:
  *
- * - `smtp` (default) - Nodemailer (`MAIL_SERVICE`, `MAIL_USERNAME`/`MAIL_PASSWORD`
- *   or `GOOGLE_SMTP_APP_*`, `MAIL_FROM_ADDRESS`)
+ * - `smtp` (default) - Nodemailer (`MAIL_SERVICE`, `MAIL_HOST`, `MAIL_PORT`,
+ *   `MAIL_USERNAME`/`MAIL_PASSWORD` or `GOOGLE_SMTP_APP_*`, `MAIL_FROM_ADDRESS`)
  * - `console` - logs the message; dev/test with zero mail configuration
  * - `custom` - resolves `CUSTOM_MAILER`; bring your own SES/Postmark/Resend…
  */

package/dist/provider.js

@@ -1,9 +1,9 @@
 import { ConfigService, logger, ServiceProvider } from "@veap/kernel";
-import { bindCommunicationContext } from "./context";
-import { CUSTOM_MAILER, MAILER } from "./mailer";
-import { ConsoleMailService } from "./providers/console.provider";
-import { NodemailerMailService } from "./providers/nodemailer.provider";
-import { setMailTranslatorFactory } from "./translator";
+import { bindCommunicationContext } from "./context.js";
+import { CUSTOM_MAILER, MAILER } from "./mailer.js";
+import { ConsoleMailService } from "./providers/console.provider.js";
+import { NodemailerMailService } from "./providers/nodemailer.provider.js";
+import { setMailTranslatorFactory } from "./translator.js";
 /**
  * Composition root of the communication context.
  *
@@ -11,8 +11,8 @@ import { setMailTranslatorFactory } from "./translator";
  * and binds it into `CommunicationContext`, so facades and services never
  * look transports up themselves:
  *
- * - `smtp` (default) - Nodemailer (`MAIL_SERVICE`, `MAIL_USERNAME`/`MAIL_PASSWORD`
- *   or `GOOGLE_SMTP_APP_*`, `MAIL_FROM_ADDRESS`)
+ * - `smtp` (default) - Nodemailer (`MAIL_SERVICE`, `MAIL_HOST`, `MAIL_PORT`,
+ *   `MAIL_USERNAME`/`MAIL_PASSWORD` or `GOOGLE_SMTP_APP_*`, `MAIL_FROM_ADDRESS`)
  * - `console` - logs the message; dev/test with zero mail configuration
  * - `custom` - resolves `CUSTOM_MAILER`; bring your own SES/Postmark/Resend…
  */
@@ -25,24 +25,44 @@ export class CommunicationServiceProvider extends ServiceProvider {
         // selects another transport.
         this.container.register({
             token: MAILER,
-            useFactory: (config) => new NodemailerMailService({
-                getService: () => config.get("MAIL_SERVICE"),
-                getUsername: () => config.get("GOOGLE_SMTP_APP_USERNAME") ??
-                    config.get("MAIL_USERNAME"),
-                getPassword: () => config.get("GOOGLE_SMTP_APP_PASSWORD") ??
-                    config.get("MAIL_PASSWORD"),
-                getFromAddress: () => config.get("MAIL_FROM_ADDRESS"),
-            }),
+            useFactory: (config) => {
+                const getEnv = (key) => {
+                    return (config?.get?.(key) ??
+                        (typeof process !== "undefined" ? process.env[key] : undefined));
+                };
+                return new NodemailerMailService({
+                    getService: () => getEnv("MAIL_SERVICE"),
+                    getHost: () => getEnv("MAIL_HOST"),
+                    getPort: () => getEnv("MAIL_PORT"),
+                    getSecure: () => {
+                        const val = getEnv("MAIL_SECURE");
+                        return val ? val === "true" || val === "1" : undefined;
+                    },
+                    getIgnoreTLS: () => {
+                        const val = getEnv("MAIL_IGNORE_TLS");
+                        return val ? val === "true" || val === "1" : undefined;
+                    },
+                    getUsername: () => getEnv("GOOGLE_SMTP_APP_USERNAME") ?? getEnv("MAIL_USERNAME"),
+                    getPassword: () => getEnv("GOOGLE_SMTP_APP_PASSWORD") ?? getEnv("MAIL_PASSWORD"),
+                    getFromAddress: () => getEnv("MAIL_FROM_ADDRESS"),
+                    getFromName: () => getEnv("MAIL_FROM_NAME"),
+                });
+            },
             inject: [ConfigService],
             singleton: true,
         });
     }
     async boot() {
-        // Bind the intl translation factory for transport templates (adapters
-        // must not import the package's own entry points - ADR-006). It is
-        // invoked per send, so the locale reflects the current request.
-        setMailTranslatorFactory(async () => (key) => key);
-        const config = await this.container.resolve(ConfigService);
+        // Bind the default translation factory that supports `{placeholder}`
+        // interpolation into the message text.
+        setMailTranslatorFactory(async () => (key, params) => {
+            if (!params)
+                return key;
+            return Object.entries(params).reduce((acc, [k, v]) => acc.replaceAll(`{${k}}`, String(v)), key);
+        });
+        const config = this.container.has(ConfigService)
+            ? await this.container.resolve(ConfigService)
+            : undefined;
         const mailer = await this.selectTransport(config);
         // Rebind the port token to the selected transport and expose it through
         // the typed context boundary.
@@ -55,7 +75,11 @@ export class CommunicationServiceProvider extends ServiceProvider {
         logger.debug("veap:communication", `Mail transport bound: ${mailer.constructor.name}`);
     }
     async selectTransport(config) {
-        const transport = config.get("MAIL_TRANSPORT")?.trim().toLowerCase();
+        const getVal = (key) => {
+            return (config?.get?.(key) ??
+                (typeof process !== "undefined" ? process.env[key] : undefined));
+        };
+        const transport = getVal("MAIL_TRANSPORT")?.trim().toLowerCase();
         if (transport === "custom") {
             if (!this.container.has(CUSTOM_MAILER)) {
                 throw new Error("[Communication] MAIL_TRANSPORT=custom but no provider is registered under the CUSTOM_MAILER token (register an IMailer in a ServiceProvider).");
@@ -65,13 +89,14 @@ export class CommunicationServiceProvider extends ServiceProvider {
         if (transport === "console") {
             return new ConsoleMailService((line) => logger.info("veap:mail", line));
         }
-        const hasSmtpCredentials = Boolean(config.get("GOOGLE_SMTP_APP_USERNAME") || config.get("MAIL_USERNAME")) &&
-            Boolean(config.get("GOOGLE_SMTP_APP_PASSWORD") || config.get("MAIL_PASSWORD"));
-        if (!transport && !hasSmtpCredentials) {
-            logger.warn("veap:communication", "MAIL_TRANSPORT is not set and no SMTP credentials (MAIL_USERNAME/MAIL_PASSWORD) are configured. Defaulting to ConsoleMailService (emails will be logged to server console).");
+        const hasSmtpCredentials = Boolean(getVal("GOOGLE_SMTP_APP_USERNAME") || getVal("MAIL_USERNAME")) &&
+            Boolean(getVal("GOOGLE_SMTP_APP_PASSWORD") || getVal("MAIL_PASSWORD"));
+        const hasSmtpHostOrService = Boolean(getVal("MAIL_HOST") || getVal("MAIL_SERVICE"));
+        if (!transport && !hasSmtpCredentials && !hasSmtpHostOrService) {
+            logger.warn("veap:communication", "MAIL_TRANSPORT is not set and no SMTP credentials (MAIL_USERNAME/MAIL_PASSWORD) or host (MAIL_HOST) are configured. Defaulting to ConsoleMailService (emails will be logged to server console).");
             return new ConsoleMailService((line) => logger.info("veap:mail", line));
         }
-        // Default ("smtp" / unset with credentials): whatever register() wired - Nodemailer.
+        // Default ("smtp" / unset with credentials/host): whatever register() wired - Nodemailer.
         return this.container.resolve(MAILER);
     }
 }

package/dist/providers/console.provider.d.ts

@@ -1,8 +1,7 @@
-import type { MailMessage } from ".././mail-message";
-import type { IMailer } from ".././mailer";
+import type { MailMessage } from "../mail-message.js";
+import type { IMailer } from "../mailer.js";
 /**
- * Console transport implementing the {@link IMailer} port.
- *
+ * Console transport implementing the {@link IMailer} port.\n *
  * A pure delivery service for development and testing: prints the
  * `MailMessage` instead of dialling an SMTP server. Selected with
  * `MAIL_TRANSPORT=console`. It knows nothing about message semantics -

package/dist/providers/console.provider.js

@@ -1,6 +1,5 @@
 /**
- * Console transport implementing the {@link IMailer} port.
- *
+ * Console transport implementing the {@link IMailer} port.\n *
  * A pure delivery service for development and testing: prints the
  * `MailMessage` instead of dialling an SMTP server. Selected with
  * `MAIL_TRANSPORT=console`. It knows nothing about message semantics -

package/dist/providers/nodemailer.provider.d.ts

@@ -1,6 +1,17 @@
 import type { SendMailOptions } from "nodemailer";
-import type { MailMessage, MailRecipient } from ".././mail-message";
-import type { IMailer } from ".././mailer";
+import type { MailMessage, MailRecipient } from "../mail-message.js";
+import type { IMailer } from "../mailer.js";
+export interface NodemailerMailConfig {
+    getService?: () => string | undefined;
+    getHost?: () => string | undefined;
+    getPort?: () => number | string | undefined;
+    getSecure?: () => boolean | undefined;
+    getIgnoreTLS?: () => boolean | undefined;
+    getUsername?: () => string | undefined;
+    getPassword?: () => string | undefined;
+    getFromAddress?: () => string | undefined;
+    getFromName?: () => string | undefined;
+}
 /**
  * SMTP transport (Nodemailer) implementing the {@link IMailer} port.
  *
@@ -16,12 +27,7 @@ import type { IMailer } from ".././mailer";
 export declare class NodemailerMailService implements IMailer {
     private transporter;
     private fromAddress;
-    constructor(config: {
-        getService: () => string;
-        getUsername: () => string | undefined;
-        getPassword: () => string | undefined;
-        getFromAddress: () => string | undefined;
-    });
+    constructor(config: NodemailerMailConfig);
     /** The sender used when a message does not specify one. */
     get defaultFrom(): MailRecipient;
     /** Exposed for tests and provider-agnostic integrations. */

package/dist/providers/nodemailer.provider.js

@@ -15,16 +15,59 @@ export class NodemailerMailService {
     transporter;
     fromAddress;
     constructor(config) {
-        this.fromAddress =
-            config.getFromAddress() ||
-                (config.getUsername() ? `Veap <${config.getUsername()}>` : "Veap");
-        this.transporter = nodemailer.createTransport({
-            service: config.getService(),
-            auth: {
-                user: config.getUsername(),
-                pass: config.getPassword(),
-            },
-        });
+        const fromAddress = config.getFromAddress?.();
+        const fromName = config.getFromName?.();
+        const username = config.getUsername?.();
+        const password = config.getPassword?.();
+        if (fromAddress) {
+            this.fromAddress =
+                fromName && !fromAddress.includes("<")
+                    ? `${fromName} <${fromAddress}>`
+                    : fromAddress;
+        }
+        else if (username) {
+            this.fromAddress = fromName
+                ? `${fromName} <${username}>`
+                : `Veap <${username}>`;
+        }
+        else {
+            this.fromAddress = "Veap";
+        }
+        const host = config.getHost?.();
+        const port = config.getPort?.();
+        const service = config.getService?.();
+        const secure = config.getSecure?.();
+        const ignoreTLS = config.getIgnoreTLS?.();
+        const auth = username || password
+            ? {
+                user: username,
+                pass: password,
+            }
+            : undefined;
+        if (host) {
+            const parsedPort = port ? Number(port) : 587;
+            this.transporter = nodemailer.createTransport({
+                host,
+                port: parsedPort,
+                secure: secure !== undefined ? Boolean(secure) : parsedPort === 465,
+                ignoreTLS: Boolean(ignoreTLS),
+                auth,
+            });
+        }
+        else if (service) {
+            this.transporter = nodemailer.createTransport({
+                service,
+                auth,
+            });
+        }
+        else {
+            // Default local or fallback SMTP transport
+            this.transporter = nodemailer.createTransport({
+                host: "localhost",
+                port: 587,
+                auth,
+            });
+        }
     }
     /** The sender used when a message does not specify one. */
     get defaultFrom() {

package/dist/translator.d.ts

@@ -7,6 +7,10 @@
  * directly and the package never imports its own entry points (ADR-006).
  */
 export type Translator = (key: string, params?: Record<string, unknown>) => string;
+/**
+ * Helper to interpolate template placeholders like `{name}` or `{code}`.
+ */
+export declare function interpolateMailText(text: string, params?: Record<string, unknown>): string;
 /**
  * Binds the translation factory. Invoked per message build, so the locale
  * always reflects the current request.

package/dist/translator.js

@@ -1,4 +1,12 @@
 let translatorFactory = null;
+/**
+ * Helper to interpolate template placeholders like `{name}` or `{code}`.
+ */
+export function interpolateMailText(text, params) {
+    if (!params)
+        return text;
+    return Object.entries(params).reduce((acc, [k, v]) => acc.replaceAll(`{${k}}`, String(v)), text);
+}
 /**
  * Binds the translation factory. Invoked per message build, so the locale
  * always reflects the current request.
@@ -12,9 +20,12 @@ export function setMailTranslatorFactory(factory) {
  * (unit tests, early boot).
  */
 export async function getMailTranslator() {
-    if (translatorFactory)
-        return translatorFactory();
-    return (key, params) => params
-        ? Object.entries(params).reduce((acc, [k, v]) => acc.replaceAll(`{${k}}`, String(v)), key)
-        : key;
+    if (translatorFactory) {
+        const fn = await translatorFactory();
+        return (key, params) => {
+            const translated = fn(key, params);
+            return interpolateMailText(translated, params);
+        };
+    }
+    return (key, params) => interpolateMailText(key, params);
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@veap/mail",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "description": "Mail and communication transport abstraction for Veap",
   "bugs": "https://github.com/veapjs/veap-mail/issues",
   "repository": {
@@ -28,7 +28,7 @@
     "test": "vitest run"
   },
   "dependencies": {
-    "@veap/kernel": "0.1.0",
+    "@veap/kernel": "0.1.1",
     "nodemailer": "^10.0.1"
   },
   "devDependencies": {