@veap/mail 0.0.0-stage → 0.1.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Damian Miller
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,128 @@
-# Temporary Holding Version
+[![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)
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+# @veap/mail
+
+Modular email and notification transport abstraction with support for
+Nodemailer, SMTP, Console logging, and custom mail drivers for Veap applications.
+
+## Overview
+
+`@veap/mail` provides a unified messaging interface decoupling application
+logic from email delivery protocols. It supports zero-configuration development
+environments with automatic console logging, robust SMTP / Nodemailer delivery
+in production, and a custom driver port (`CUSTOM_MAILER`) for external email
+services such as AWS SES, Postmark, or Resend.
+
+## Features
+
+- **Multiple mail transports**: Built-in support for Nodemailer (SMTP, Google
+  App Passwords) and zero-config `ConsoleMailService` for local development.
+- **Unified `sendMail` facade**: Simple, consistent API for sending plain text,
+  HTML, and rich multipart emails.
+- **Authentication notification helpers**: Out-of-the-box functions for
+  `sendResetPassword` and `sendVerifyEmail` with customizable templates.
+- **IoC-driven lifecycle**: `MailServiceProvider` handles automatic driver
+  selection and credentials parsing during application boot.
+- **Custom mailer support**: Extendable driver architecture via the
+  `CUSTOM_MAILER` token.
+
+## Installation
+
+```bash
+# Using bun
+bun add @veap/mail @veap/kernel
+
+# Using pnpm
+pnpm add @veap/mail @veap/kernel
+
+# Using npm
+npm install @veap/mail @veap/kernel
+```
+
+## Configuration
+
+`@veap/mail` detects transports automatically from environment variables:
+
+| Environment Variable                     | Description                                          |
+| ---------------------------------------- | ---------------------------------------------------- |
+| `MAIL_TRANSPORT`                         | Delivery driver (`smtp`, `console`, or `custom`)     |
+| `MAIL_SERVICE`                           | Well-known Nodemailer service (for example, `gmail`) |
+| `MAIL_USERNAME` / `MAIL_PASSWORD`        | Standard SMTP credentials                            |
+| `GOOGLE_SMTP_APP_USERNAME` / `_PASSWORD` | Alternative Google App password credentials          |
+| `MAIL_FROM_ADDRESS`                      | Default sender email address                         |
+
+When no credentials or `MAIL_TRANSPORT` are set, `@veap/mail` defaults safely
+to `ConsoleMailService` so local development and tests run without network errors.
+
+## Usage
+
+### Register in Application Builder
+
+Include `MailServiceProvider` in your application composition root:
+
+```ts
+import { Application } from "@veap/kernel";
+import { MailServiceProvider } from "@veap/mail";
+
+export const app = Application.configure().use(MailServiceProvider).create();
+```
+
+### Sending Emails
+
+Send transactional messages from services or server actions:
+
+```ts
+import { sendMail } from "@veap/mail";
+
+await sendMail({
+  to: "user@example.com",
+  subject: "Welcome to Our Platform",
+  text: "Thank you for creating an account with us!",
+  html: "<h1>Welcome!</h1><p>Thank you for creating an account with us!</p>",
+});
+```
+
+### Registering a Custom Mailer
+
+Implement the `IMailer` interface and bind it under `CUSTOM_MAILER`:
+
+```ts
+import { ServiceProvider } from "@veap/kernel";
+import { CUSTOM_MAILER, type IMailer, type MailMessage } from "@veap/mail";
+
+export class ResendMailService implements IMailer {
+  async send(message: MailMessage): Promise<void> {
+    // Send via third-party SDK (e.g., resend.emails.send)
+  }
+}
+
+export class CustomMailServiceProvider extends ServiceProvider {
+  register(): void {
+    this.container.register({
+      token: CUSTOM_MAILER,
+      useClass: ResendMailService,
+      singleton: true,
+    });
+  }
+}
+```
+
+## Subpath Exports
+
+| Export Path  | Content                                                                                  |
+| ------------ | ---------------------------------------------------------------------------------------- |
+| `@veap/mail` | Mail facades (`sendMail`), providers, interfaces (`IMailer`, `MailMessage`), and context |
+
+## Documentation
+
+For full guides and transport configuration options, visit:
+
+- **Official Website**: [https://veap.pl](https://veap.pl)
+- **Documentation**: [https://veap.pl/docs](https://veap.pl/docs)
+- **GitHub Repository**: [https://github.com/veapjs/veap-mail](https://github.com/veapjs/veap-mail)
+
+## License
+
+MIT

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

@@ -0,0 +1,22 @@
+import type { IMailer } from "./mailer.js";
+/**
+ * Typed boundary between the communication use cases and their consumers
+ * (facades, application services). The same pattern as
+ * `application/auth/context.ts` and `application/plugins/context.ts`.
+ *
+ * The composition root (`CommunicationServiceProvider`) selects the mail
+ * transport once at boot and binds it here.
+ */
+export interface CommunicationContext {
+    mailer: IMailer;
+}
+/**
+ * Binds the resolved communication services. Called once by the composition root.
+ */
+export declare function bindCommunicationContext(context: CommunicationContext): void;
+/**
+ * Returns the bound communication services.
+ *
+ * @throws If the communication service provider has not booted yet.
+ */
+export declare function communicationContext(): CommunicationContext;

package/dist/context.js

@@ -0,0 +1,20 @@
+import { AppError } from "@veap/kernel";
+const globalForCommunicationContext = globalThis;
+/**
+ * Binds the resolved communication services. Called once by the composition root.
+ */
+export function bindCommunicationContext(context) {
+    globalForCommunicationContext.__VEAP_COMMUNICATION_CONTEXT__ = context;
+}
+/**
+ * Returns the bound communication services.
+ *
+ * @throws If the communication service provider has not booted yet.
+ */
+export function communicationContext() {
+    const context = globalForCommunicationContext.__VEAP_COMMUNICATION_CONTEXT__;
+    if (!context) {
+        throw AppError.Internal("[Communication] Context is not bound. CommunicationServiceProvider must boot before the communication facades are used.");
+    }
+    return context;
+}

package/dist/index.d.ts

@@ -0,0 +1,11 @@
+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

@@ -0,0 +1,10 @@
+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-message.d.ts

@@ -0,0 +1,53 @@
+/**
+ * Transport-agnostic mail DTOs.
+ *
+ * These are the *only* types a mail transport adapter is allowed to require:
+ * the port (`IMailer`) speaks this vocabulary, never a concrete provider's
+ * (Nodemailer, SES, Postmark, Resend…). Adapters map `MailMessage` onto their
+ * own SDK types - that mapping is precisely what makes an adapter an adapter.
+ */
+/** A named email address, e.g. `{ name: "Veap", address: "noreply@app.dev" }`. */
+export interface MailAddress {
+    name?: string;
+    address: string;
+}
+/** A file attached to the message. */
+export interface MailAttachment {
+    filename?: string;
+    /** Inline content (string or Buffer). Mutually exclusive with `path`. */
+    content?: string | Buffer;
+    /** File path to read the attachment from. Mutually exclusive with `content`. */
+    path?: string;
+    contentType?: string;
+    /** Content-ID for inline images referenced from HTML (`cid:`). */
+    cid?: string;
+    encoding?: string;
+}
+/** An address or a plain string address. */
+export type MailRecipient = string | MailAddress;
+/**
+ * The framework's mail message.
+ *
+ * Intentionally minimal and framework-neutral: a transport adapter maps it
+ * onto its provider's native shape. Anything provider-specific (SES
+ * `SourceArn`, Postmark `Metadata`, Resend tags…) belongs to adapter
+ * configuration, not to this contract.
+ */
+export interface MailMessage {
+    /** Primary recipient(s). */
+    to: MailRecipient | MailRecipient[];
+    subject: string;
+    /** Plain-text body. */
+    text?: string;
+    /** HTML body. At least one of `text` / `html` should be present. */
+    html?: string;
+    /** Overrides the transport's default sender (e.g. `MAIL_FROM_ADDRESS`). */
+    from?: MailRecipient;
+    cc?: MailRecipient | MailRecipient[];
+    bcc?: MailRecipient | MailRecipient[];
+    replyTo?: MailRecipient;
+    attachments?: MailAttachment[];
+    priority?: "high" | "normal" | "low";
+    /** Custom message headers. */
+    headers?: Record<string, string>;
+}

package/dist/mail-message.js

@@ -0,0 +1,9 @@
+/**
+ * Transport-agnostic mail DTOs.
+ *
+ * These are the *only* types a mail transport adapter is allowed to require:
+ * the port (`IMailer`) speaks this vocabulary, never a concrete provider's
+ * (Nodemailer, SES, Postmark, Resend…). Adapters map `MailMessage` onto their
+ * own SDK types - that mapping is precisely what makes an adapter an adapter.
+ */
+export {};

package/dist/mail.d.ts

@@ -0,0 +1,19 @@
+import type { MailMessage } from "./mail-message.js";
+/**
+ * Mailables - the domain vocabulary of email.
+ *
+ * Transports deliver; mailables decide *what* is sent. Each helper builds a
+ * `MailMessage` (localized via the injected translator) and hands it to the
+ * bound `IMailer` port. This is the Laravel split: `Mailable` defines the
+ * content, `Transport` only delivers it - a transport never knows whether it
+ * is carrying a verification code or a newsletter.
+ *
+ * Application services (auth flows) and plugins call these helpers; swapping
+ * the transport never touches them, and adding a new mail kind never touches
+ * a transport.
+ */
+export declare function sendMail(message: MailMessage): Promise<void>;
+export declare function sendVerifyEmail(email: string, code: string): Promise<void>;
+export declare function sendResetPassword(email: string, code: string): Promise<void>;
+export declare function sendRecoveryCode(email: string, recoveryCode: string): Promise<void>;
+export declare function send2FACode(email: string, code: string): Promise<void>;

package/dist/mail.js

@@ -0,0 +1,52 @@
+import { communicationContext } from "./context.js";
+import { getMailTranslator } from "./translator.js";
+/**
+ * Mailables - the domain vocabulary of email.
+ *
+ * Transports deliver; mailables decide *what* is sent. Each helper builds a
+ * `MailMessage` (localized via the injected translator) and hands it to the
+ * bound `IMailer` port. This is the Laravel split: `Mailable` defines the
+ * content, `Transport` only delivers it - a transport never knows whether it
+ * is carrying a verification code or a newsletter.
+ *
+ * Application services (auth flows) and plugins call these helpers; swapping
+ * the transport never touches them, and adding a new mail kind never touches
+ * a transport.
+ */
+export async function sendMail(message) {
+    return communicationContext().mailer.sendMail(message);
+}
+export async function sendVerifyEmail(email, code) {
+    const t = await getMailTranslator();
+    return sendMail({
+        to: email,
+        subject: t("Verify Email"),
+        text: t("Verify your email address with your code: {code}", { code }),
+    });
+}
+export async function sendResetPassword(email, code) {
+    const t = await getMailTranslator();
+    return sendMail({
+        to: email,
+        subject: t("Password Reset"),
+        text: t("Verify password reset with code: {code}", { code }),
+    });
+}
+export async function sendRecoveryCode(email, recoveryCode) {
+    const t = await getMailTranslator();
+    return sendMail({
+        to: email,
+        subject: t("Recovery Code"),
+        text: t("Your recovery code is: {recoveryCode}", { recoveryCode }),
+    });
+}
+export async function send2FACode(email, code) {
+    const t = await getMailTranslator();
+    return sendMail({
+        to: email,
+        subject: t("Your 2FA Code"),
+        text: t("Your verification code is: {code}. It will expire in 10 minutes.", {
+            code,
+        }),
+    });
+}

package/dist/mailer.d.ts

@@ -0,0 +1,38 @@
+import type { Token } from "@veap/kernel";
+import type { MailMessage } from "./mail-message.js";
+/**
+ * Mailer port.
+ *
+ * A pure delivery service: it transmits `MailMessage`s and knows nothing
+ * about *why* an email is being sent. Semantics - verification codes, resets,
+ * 2FA, templates, i18n - belong to the domains that own those flows and are
+ * expressed as mailables (`application/communication/mail.ts`), which build a
+ * `MailMessage` and hand it to this port.
+ *
+ * This mirrors Laravel's split: `Transport` (the `MailManager`'s drivers)
+ * only delivers a raw message, while `Mailable` classes define the content.
+ */
+export interface IMailer {
+    /** Delivers a message. The single, transport-agnostic operation. */
+    sendMail(message: MailMessage): Promise<void>;
+}
+/**
+ * Injection token for the mailer port.
+ *
+ * A global symbol keeps the token stable across HMR / dual-package
+ * boundaries, the same reason the container keys class tokens with
+ * `Symbol.for(...)`.
+ */
+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.
+ *
+ * Set `MAIL_TRANSPORT=custom` and register an `IMailer` implementation under
+ * 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: Token<IMailer>;

package/dist/mailer.js

@@ -0,0 +1,20 @@
+/**
+ * Injection token for the mailer port.
+ *
+ * A global symbol keeps the token stable across HMR / dual-package
+ * boundaries, the same reason the container keys class tokens with
+ * `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.
+ *
+ * Set `MAIL_TRANSPORT=custom` and register an `IMailer` implementation under
+ * this token (e.g. SES, Postmark, Resend, an outbox pattern…) to route all
+ * mail through your own delivery system without touching the framework.
+ */
+export const CUSTOM_MAILER = Symbol.for("veap:communication:custom-mailer");

package/dist/provider.d.ts

@@ -0,0 +1,19 @@
+import { ServiceProvider } from "@veap/kernel";
+/**
+ * Composition root of the communication context.
+ *
+ * Selects the mail transport exactly once (in `boot()`) from `MAIL_TRANSPORT`
+ * and binds it into `CommunicationContext`, so facades and services never
+ * look transports up themselves:
+ *
+ * - `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…
+ */
+export declare class CommunicationServiceProvider extends ServiceProvider {
+    register(): void;
+    boot(): Promise<void>;
+    private selectTransport;
+}
+export declare const MailServiceProvider: typeof CommunicationServiceProvider;

package/dist/provider.js

@@ -0,0 +1,103 @@
+import { ConfigService, logger, ServiceProvider } from "@veap/kernel";
+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.
+ *
+ * Selects the mail transport exactly once (in `boot()`) from `MAIL_TRANSPORT`
+ * and binds it into `CommunicationContext`, so facades and services never
+ * look transports up themselves:
+ *
+ * - `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…
+ */
+export class CommunicationServiceProvider extends ServiceProvider {
+    register() {
+        // Default registration: the Nodemailer transport under the port token,
+        // with config getters wired here at the composition root (the adapter
+        // itself takes plain functions, so it stays container-agnostic).
+        // Replaced with a `useValue` binding in `boot()` when MAIL_TRANSPORT
+        // selects another transport.
+        this.container.register({
+            token: MAILER,
+            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 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.
+        this.container.register({
+            token: MAILER,
+            useValue: mailer,
+            singleton: true,
+        });
+        bindCommunicationContext({ mailer });
+        logger.debug("veap:communication", `Mail transport bound: ${mailer.constructor.name}`);
+    }
+    async selectTransport(config) {
+        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).");
+            }
+            return this.container.resolve(CUSTOM_MAILER);
+        }
+        if (transport === "console") {
+            return new ConsoleMailService((line) => logger.info("veap:mail", line));
+        }
+        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/host): whatever register() wired - Nodemailer.
+        return this.container.resolve(MAILER);
+    }
+}
+export const MailServiceProvider = CommunicationServiceProvider;

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

@@ -0,0 +1,14 @@
+import type { MailMessage } from "../mail-message.js";
+import type { IMailer } from "../mailer.js";
+/**
+ * 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 -
+ * content comes fully built from the mailables.
+ */
+export declare class ConsoleMailService implements IMailer {
+    private readonly log;
+    constructor(log?: (line: string) => void);
+    sendMail(message: MailMessage): Promise<void>;
+}

package/dist/providers/console.provider.js

@@ -0,0 +1,33 @@
+/**
+ * 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 -
+ * content comes fully built from the mailables.
+ */
+export class ConsoleMailService {
+    log;
+    constructor(log = console.info) {
+        this.log = log;
+    }
+    async sendMail(message) {
+        const to = Array.isArray(message.to)
+            ? message.to
+                .map((r) => (typeof r === "string" ? r : r.address))
+                .join(", ")
+            : typeof message.to === "string"
+                ? message.to
+                : message.to.address;
+        this.log([
+            `📬 [MAIL:console] to=${to}`,
+            `subject="${message.subject}"`,
+            message.text ? `text="${message.text}"` : null,
+            message.html ? `(html ${message.html.length} bytes)` : null,
+            message.attachments?.length
+                ? `(attachments: ${message.attachments.length})`
+                : null,
+        ]
+            .filter(Boolean)
+            .join(" "));
+    }
+}

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

@@ -0,0 +1,36 @@
+import type { SendMailOptions } from "nodemailer";
+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.
+ *
+ * A pure delivery service: takes `MailMessage`s and transmits them. It knows
+ * nothing about verification codes, resets or i18n - content is decided by
+ * the mailables in `application/communication/mail.ts` (the Laravel split:
+ * `Mailable` = content, `Transport` = delivery).
+ *
+ * The only place in the codebase that knows Nodemailer exists; Nodemailer's
+ * field names are a superset of the DTO, so mapping is one spread plus a
+ * default sender.
+ */
+export declare class NodemailerMailService implements IMailer {
+    private transporter;
+    private fromAddress;
+    constructor(config: NodemailerMailConfig);
+    /** The sender used when a message does not specify one. */
+    get defaultFrom(): MailRecipient;
+    /** Exposed for tests and provider-agnostic integrations. */
+    toSendMailOptions(message: MailMessage): SendMailOptions;
+    sendMail(message: MailMessage): Promise<void>;
+}

package/dist/providers/nodemailer.provider.js

@@ -0,0 +1,86 @@
+import nodemailer from "nodemailer";
+/**
+ * SMTP transport (Nodemailer) implementing the {@link IMailer} port.
+ *
+ * A pure delivery service: takes `MailMessage`s and transmits them. It knows
+ * nothing about verification codes, resets or i18n - content is decided by
+ * the mailables in `application/communication/mail.ts` (the Laravel split:
+ * `Mailable` = content, `Transport` = delivery).
+ *
+ * The only place in the codebase that knows Nodemailer exists; Nodemailer's
+ * field names are a superset of the DTO, so mapping is one spread plus a
+ * default sender.
+ */
+export class NodemailerMailService {
+    transporter;
+    fromAddress;
+    constructor(config) {
+        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() {
+        return this.fromAddress;
+    }
+    /** Exposed for tests and provider-agnostic integrations. */
+    toSendMailOptions(message) {
+        return {
+            ...message,
+            from: message.from ?? this.fromAddress,
+        };
+    }
+    async sendMail(message) {
+        await this.transporter.sendMail(this.toSendMailOptions(message));
+    }
+}

package/dist/translator.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Translation hook for mailables.
+ *
+ * Lives in the application layer because building localized messages is a
+ * use-case concern; the intl implementation (infrastructure) is injected here
+ * once by `CommunicationServiceProvider` - so mailables never import intl
+ * 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.
+ */
+export declare function setMailTranslatorFactory(factory: () => Promise<Translator>): void;
+/**
+ * Returns the bound translator, falling back to simple `{param}`
+ * interpolation into the raw key when intl has not bound one yet
+ * (unit tests, early boot).
+ */
+export declare function getMailTranslator(): Promise<Translator>;

package/dist/translator.js

@@ -0,0 +1,31 @@
+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.
+ */
+export function setMailTranslatorFactory(factory) {
+    translatorFactory = factory;
+}
+/**
+ * Returns the bound translator, falling back to simple `{param}`
+ * interpolation into the raw key when intl has not bound one yet
+ * (unit tests, early boot).
+ */
+export async function getMailTranslator() {
+    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,41 @@
 {
   "name": "@veap/mail",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.1",
+  "description": "Mail and communication transport abstraction for Veap",
+  "bugs": "https://github.com/veapjs/veap-mail/issues",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/veapjs/veap-mail.git"
+  },
+  "type": "module",
+  "license": "MIT",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "clean": "rimraf dist",
+    "build": "rimraf dist && tsc",
+    "dev": "tsc --watch",
+    "test": "vitest run"
+  },
+  "dependencies": {
+    "@veap/kernel": "0.1.1",
+    "nodemailer": "^10.0.1"
+  },
+  "devDependencies": {
+    "@types/node": "^22.20.2",
+    "@types/nodemailer": "^8.0.1",
+    "rimraf": "^6.1.3",
+    "typescript": "6.0.3",
+    "vitest": "^5.0.0"
+  }
+}