@veloxts/mail 0.6.51

package/dist/plugin.d.ts

@@ -0,0 +1,117 @@
+/**
+ * Mail Plugin
+ *
+ * VeloxTS plugin for integrating email functionality into the framework.
+ */
+import type { FastifyInstance } from 'fastify';
+import '@veloxts/core';
+import { type MailManager } from './manager.js';
+import type { MailPluginOptions } from './types.js';
+/**
+ * Symbol for storing mail manager on Fastify instance.
+ * Using a symbol prevents naming conflicts with other plugins.
+ */
+declare const MAIL_MANAGER_KEY: unique symbol;
+/**
+ * Extend Fastify types with mail manager.
+ */
+declare module 'fastify' {
+    interface FastifyInstance {
+        [MAIL_MANAGER_KEY]?: MailManager;
+    }
+    interface FastifyRequest {
+        mail?: MailManager;
+    }
+}
+/**
+ * Extend VeloxTS BaseContext with mail manager.
+ *
+ * This enables `ctx.mail` in procedure handlers with full type safety
+ * and autocomplete when the mail plugin is registered.
+ *
+ * The property is NON-optional since the plugin guarantees it exists
+ * after registration.
+ */
+declare module '@veloxts/core' {
+    interface BaseContext {
+        /** Mail manager for sending emails via templates */
+        mail: MailManager;
+    }
+}
+/**
+ * Create the mail plugin for VeloxTS.
+ *
+ * Each Fastify instance gets its own mail manager, ensuring proper test isolation
+ * and supporting multiple Fastify instances in the same process.
+ *
+ * @param options - Mail plugin options
+ * @returns Fastify plugin
+ *
+ * @example
+ * ```typescript
+ * import { createApp } from '@veloxts/core';
+ * import { mailPlugin } from '@veloxts/mail';
+ *
+ * const app = createApp();
+ *
+ * app.use(mailPlugin({
+ *   driver: 'resend',
+ *   config: { apiKey: process.env.RESEND_API_KEY! },
+ *   from: { email: 'hello@myapp.com', name: 'My App' },
+ * }));
+ *
+ * // In procedures:
+ * await ctx.mail.send(WelcomeEmail, {
+ *   to: 'user@example.com',
+ *   data: { user, activationUrl },
+ * });
+ * ```
+ */
+export declare function mailPlugin(options?: MailPluginOptions): (fastify: FastifyInstance) => Promise<void>;
+/**
+ * Get the mail manager from a Fastify instance.
+ *
+ * @param fastify - Fastify instance with mail plugin registered
+ * @throws Error if mail plugin is not registered
+ */
+export declare function getMailFromInstance(fastify: FastifyInstance): MailManager;
+/**
+ * Initialize mail manager standalone (without Fastify).
+ *
+ * Useful for CLI commands or background jobs. This creates a separate
+ * mail instance that is independent from any Fastify instances.
+ *
+ * @example
+ * ```typescript
+ * import { initMail, closeMail } from '@veloxts/mail';
+ *
+ * const mail = await initMail({
+ *   driver: 'resend',
+ *   config: { apiKey: process.env.RESEND_API_KEY! },
+ *   from: { email: 'hello@myapp.com', name: 'My App' },
+ * });
+ *
+ * // Use mail directly
+ * await mail.send(WelcomeEmail, { to: 'user@example.com', data: { ... } });
+ *
+ * // Clean up when done
+ * await closeMail();
+ * ```
+ */
+export declare function initMail(options?: MailPluginOptions): Promise<MailManager>;
+/**
+ * Get the standalone mail manager.
+ *
+ * @throws Error if mail is not initialized via initMail()
+ */
+export declare function getMail(): MailManager;
+/**
+ * Close the standalone mail connection.
+ */
+export declare function closeMail(): Promise<void>;
+/**
+ * Reset standalone mail instance (for testing purposes).
+ * @internal
+ */
+export declare function _resetStandaloneMail(): void;
+export {};

package/dist/plugin.js

@@ -0,0 +1,145 @@
+/**
+ * Mail Plugin
+ *
+ * VeloxTS plugin for integrating email functionality into the framework.
+ */
+import fp from 'fastify-plugin';
+// Side-effect import to enable module augmentation (TypeScript requires module reference)
+import '@veloxts/core';
+import { createMailManager } from './manager.js';
+/**
+ * Symbol for storing mail manager on Fastify instance.
+ * Using a symbol prevents naming conflicts with other plugins.
+ */
+const MAIL_MANAGER_KEY = Symbol.for('@veloxts/mail:manager');
+/**
+ * Standalone mail instance for CLI commands and background jobs.
+ * This is separate from the plugin to avoid test isolation issues.
+ */
+let standaloneMailInstance = null;
+/**
+ * Create the mail plugin for VeloxTS.
+ *
+ * Each Fastify instance gets its own mail manager, ensuring proper test isolation
+ * and supporting multiple Fastify instances in the same process.
+ *
+ * @param options - Mail plugin options
+ * @returns Fastify plugin
+ *
+ * @example
+ * ```typescript
+ * import { createApp } from '@veloxts/core';
+ * import { mailPlugin } from '@veloxts/mail';
+ *
+ * const app = createApp();
+ *
+ * app.use(mailPlugin({
+ *   driver: 'resend',
+ *   config: { apiKey: process.env.RESEND_API_KEY! },
+ *   from: { email: 'hello@myapp.com', name: 'My App' },
+ * }));
+ *
+ * // In procedures:
+ * await ctx.mail.send(WelcomeEmail, {
+ *   to: 'user@example.com',
+ *   data: { user, activationUrl },
+ * });
+ * ```
+ */
+export function mailPlugin(options = {}) {
+    return fp(async (fastify) => {
+        // Create a new mail manager for this Fastify instance
+        const mailManager = await createMailManager(options);
+        // Store on Fastify instance using symbol key (type-safe via Object.defineProperty)
+        Object.defineProperty(fastify, MAIL_MANAGER_KEY, {
+            value: mailManager,
+            writable: false,
+            enumerable: false,
+            configurable: false,
+        });
+        // Decorate the request with mail manager
+        fastify.decorateRequest('mail', undefined);
+        // Add mail to request context
+        fastify.addHook('onRequest', async (request) => {
+            request.mail = mailManager;
+        });
+        // Close mail on server shutdown
+        fastify.addHook('onClose', async () => {
+            await mailManager.close();
+        });
+    }, {
+        name: '@veloxts/mail',
+        fastify: '5.x',
+    });
+}
+/**
+ * Get the mail manager from a Fastify instance.
+ *
+ * @param fastify - Fastify instance with mail plugin registered
+ * @throws Error if mail plugin is not registered
+ */
+export function getMailFromInstance(fastify) {
+    // Type-safe property access using Object.getOwnPropertyDescriptor
+    const descriptor = Object.getOwnPropertyDescriptor(fastify, MAIL_MANAGER_KEY);
+    const mail = descriptor?.value;
+    if (!mail) {
+        throw new Error('Mail not initialized on this Fastify instance. Make sure to register mailPlugin first.');
+    }
+    return mail;
+}
+/**
+ * Initialize mail manager standalone (without Fastify).
+ *
+ * Useful for CLI commands or background jobs. This creates a separate
+ * mail instance that is independent from any Fastify instances.
+ *
+ * @example
+ * ```typescript
+ * import { initMail, closeMail } from '@veloxts/mail';
+ *
+ * const mail = await initMail({
+ *   driver: 'resend',
+ *   config: { apiKey: process.env.RESEND_API_KEY! },
+ *   from: { email: 'hello@myapp.com', name: 'My App' },
+ * });
+ *
+ * // Use mail directly
+ * await mail.send(WelcomeEmail, { to: 'user@example.com', data: { ... } });
+ *
+ * // Clean up when done
+ * await closeMail();
+ * ```
+ */
+export async function initMail(options = {}) {
+    if (!standaloneMailInstance) {
+        standaloneMailInstance = await createMailManager(options);
+    }
+    return standaloneMailInstance;
+}
+/**
+ * Get the standalone mail manager.
+ *
+ * @throws Error if mail is not initialized via initMail()
+ */
+export function getMail() {
+    if (!standaloneMailInstance) {
+        throw new Error('Standalone mail not initialized. Call initMail() first, or use getMailFromInstance() for Fastify-based usage.');
+    }
+    return standaloneMailInstance;
+}
+/**
+ * Close the standalone mail connection.
+ */
+export async function closeMail() {
+    if (standaloneMailInstance) {
+        await standaloneMailInstance.close();
+        standaloneMailInstance = null;
+    }
+}
+/**
+ * Reset standalone mail instance (for testing purposes).
+ * @internal
+ */
+export function _resetStandaloneMail() {
+    standaloneMailInstance = null;
+}

package/dist/transports/log.d.ts

@@ -0,0 +1,32 @@
+/**
+ * Log Transport Driver
+ *
+ * Development transport that logs emails to console instead of sending.
+ */
+import type { LogConfig, MailTransport } from '../types.js';
+/**
+ * Create a log mail transport for development.
+ *
+ * @param config - Log configuration
+ * @returns Mail transport implementation
+ *
+ * @example
+ * ```typescript
+ * const transport = createLogTransport({
+ *   showHtml: true,  // Show full HTML in logs
+ * });
+ *
+ * await transport.send({
+ *   from: { email: 'from@example.com', name: 'App' },
+ *   to: [{ email: 'user@example.com' }],
+ *   subject: 'Hello',
+ *   html: '<h1>Hello World</h1>',
+ * });
+ * // Logs email details to console
+ * ```
+ */
+export declare function createLogTransport(config?: LogConfig): MailTransport;
+/**
+ * Log transport driver name.
+ */
+export declare const DRIVER_NAME: "log";

package/dist/transports/log.js

@@ -0,0 +1,101 @@
+/**
+ * Log Transport Driver
+ *
+ * Development transport that logs emails to console instead of sending.
+ */
+import { formatAddress, generateMessageId } from '../utils.js';
+/**
+ * Default log transport configuration.
+ */
+const DEFAULT_CONFIG = {
+    showHtml: false,
+    logger: console.log,
+};
+/**
+ * Create a log mail transport for development.
+ *
+ * @param config - Log configuration
+ * @returns Mail transport implementation
+ *
+ * @example
+ * ```typescript
+ * const transport = createLogTransport({
+ *   showHtml: true,  // Show full HTML in logs
+ * });
+ *
+ * await transport.send({
+ *   from: { email: 'from@example.com', name: 'App' },
+ *   to: [{ email: 'user@example.com' }],
+ *   subject: 'Hello',
+ *   html: '<h1>Hello World</h1>',
+ * });
+ * // Logs email details to console
+ * ```
+ */
+export function createLogTransport(config = {}) {
+    const options = { ...DEFAULT_CONFIG, ...config };
+    const log = options.logger;
+    const transport = {
+        async send(sendOptions) {
+            const messageId = generateMessageId();
+            const separator = '─'.repeat(60);
+            log(`\n${separator}`);
+            log('📧 EMAIL SENT (log transport)');
+            log(separator);
+            log(`Message ID: ${messageId}`);
+            log(`From:       ${formatAddress(sendOptions.from)}`);
+            log(`To:         ${sendOptions.to.map(formatAddress).join(', ')}`);
+            if (sendOptions.cc?.length) {
+                log(`CC:         ${sendOptions.cc.map(formatAddress).join(', ')}`);
+            }
+            if (sendOptions.bcc?.length) {
+                log(`BCC:        ${sendOptions.bcc.map(formatAddress).join(', ')}`);
+            }
+            if (sendOptions.replyTo) {
+                log(`Reply-To:   ${formatAddress(sendOptions.replyTo)}`);
+            }
+            log(`Subject:    ${sendOptions.subject}`);
+            if (sendOptions.attachments?.length) {
+                log(`Attachments: ${sendOptions.attachments.map((a) => a.filename).join(', ')}`);
+            }
+            if (sendOptions.tags?.length) {
+                log(`Tags:       ${sendOptions.tags.join(', ')}`);
+            }
+            if (sendOptions.headers && Object.keys(sendOptions.headers).length > 0) {
+                log('Headers:');
+                for (const [key, value] of Object.entries(sendOptions.headers)) {
+                    log(`  ${key}: ${value}`);
+                }
+            }
+            log(separator);
+            if (sendOptions.text) {
+                log('Plain Text:');
+                log(sendOptions.text);
+                log(separator);
+            }
+            if (options.showHtml) {
+                log('HTML:');
+                log(sendOptions.html);
+                log(separator);
+            }
+            else {
+                const htmlPreview = sendOptions.html.substring(0, 200);
+                log(`HTML Preview: ${htmlPreview}${sendOptions.html.length > 200 ? '...' : ''}`);
+                log(separator);
+            }
+            log('');
+            return {
+                success: true,
+                messageId,
+            };
+        },
+        async close() {
+            // Nothing to close
+        },
+    };
+    return transport;
+}
+/**
+ * Log transport driver name.
+ */
+export const DRIVER_NAME = 'log';

package/dist/transports/resend.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Resend Transport Driver
+ *
+ * Email transport using Resend API.
+ */
+import type { MailTransport, ResendConfig } from '../types.js';
+/**
+ * Create a Resend mail transport.
+ *
+ * @param config - Resend configuration
+ * @returns Mail transport implementation
+ *
+ * @example
+ * ```typescript
+ * const transport = await createResendTransport({
+ *   apiKey: process.env.RESEND_API_KEY!,
+ * });
+ *
+ * await transport.send({
+ *   from: { email: 'from@example.com', name: 'App' },
+ *   to: [{ email: 'user@example.com' }],
+ *   subject: 'Hello',
+ *   html: '<h1>Hello World</h1>',
+ * });
+ * ```
+ */
+export declare function createResendTransport(config: ResendConfig): Promise<MailTransport>;
+/**
+ * Resend transport driver name.
+ */
+export declare const DRIVER_NAME: "resend";

package/dist/transports/resend.js

@@ -0,0 +1,95 @@
+/**
+ * Resend Transport Driver
+ *
+ * Email transport using Resend API.
+ */
+import { formatAddress } from '../utils.js';
+/**
+ * Create a Resend mail transport.
+ *
+ * @param config - Resend configuration
+ * @returns Mail transport implementation
+ *
+ * @example
+ * ```typescript
+ * const transport = await createResendTransport({
+ *   apiKey: process.env.RESEND_API_KEY!,
+ * });
+ *
+ * await transport.send({
+ *   from: { email: 'from@example.com', name: 'App' },
+ *   to: [{ email: 'user@example.com' }],
+ *   subject: 'Hello',
+ *   html: '<h1>Hello World</h1>',
+ * });
+ * ```
+ */
+export async function createResendTransport(config) {
+    // Dynamic import of resend
+    const { Resend } = await import('resend');
+    const resend = new Resend(config.apiKey);
+    /**
+     * Format addresses for Resend API.
+     */
+    function formatAddresses(addresses) {
+        return addresses.map(formatAddress);
+    }
+    /**
+     * Convert attachment content to base64 for Resend API.
+     * Buffer is converted directly, string content is assumed to be raw and encoded.
+     */
+    function encodeAttachmentContent(content) {
+        if (Buffer.isBuffer(content)) {
+            return content.toString('base64');
+        }
+        // String content is assumed to be raw - encode to base64
+        return Buffer.from(content, 'utf-8').toString('base64');
+    }
+    const transport = {
+        async send(sendOptions) {
+            try {
+                const result = await resend.emails.send({
+                    from: formatAddress(sendOptions.from),
+                    to: formatAddresses(sendOptions.to),
+                    cc: sendOptions.cc ? formatAddresses(sendOptions.cc) : undefined,
+                    bcc: sendOptions.bcc ? formatAddresses(sendOptions.bcc) : undefined,
+                    replyTo: sendOptions.replyTo ? formatAddress(sendOptions.replyTo) : undefined,
+                    subject: sendOptions.subject,
+                    html: sendOptions.html,
+                    text: sendOptions.text,
+                    attachments: sendOptions.attachments?.map((att) => ({
+                        filename: att.filename,
+                        content: encodeAttachmentContent(att.content),
+                    })),
+                    headers: sendOptions.headers,
+                    tags: sendOptions.tags?.map((tag) => ({ name: tag, value: 'true' })),
+                });
+                if (result.error) {
+                    return {
+                        success: false,
+                        error: result.error.message,
+                    };
+                }
+                return {
+                    success: true,
+                    messageId: result.data?.id,
+                };
+            }
+            catch (error) {
+                const errorMessage = error instanceof Error ? error.message : String(error);
+                return {
+                    success: false,
+                    error: errorMessage,
+                };
+            }
+        },
+        async close() {
+            // Resend client doesn't need explicit closing
+        },
+    };
+    return transport;
+}
+/**
+ * Resend transport driver name.
+ */
+export const DRIVER_NAME = 'resend';

package/dist/transports/smtp.d.ts

@@ -0,0 +1,36 @@
+/**
+ * SMTP Transport Driver
+ *
+ * Email transport using Nodemailer for SMTP servers.
+ */
+import type { MailTransport, SmtpConfig } from '../types.js';
+/**
+ * Create an SMTP mail transport.
+ *
+ * @param config - SMTP configuration
+ * @returns Mail transport implementation
+ *
+ * @example
+ * ```typescript
+ * const transport = await createSmtpTransport({
+ *   host: 'smtp.gmail.com',
+ *   port: 587,
+ *   auth: {
+ *     user: 'user@gmail.com',
+ *     pass: 'app-password',
+ *   },
+ * });
+ *
+ * await transport.send({
+ *   from: { email: 'from@example.com', name: 'App' },
+ *   to: [{ email: 'user@example.com' }],
+ *   subject: 'Hello',
+ *   html: '<h1>Hello World</h1>',
+ * });
+ * ```
+ */
+export declare function createSmtpTransport(config: SmtpConfig): Promise<MailTransport>;
+/**
+ * SMTP transport driver name.
+ */
+export declare const DRIVER_NAME: "smtp";

package/dist/transports/smtp.js

@@ -0,0 +1,116 @@
+/**
+ * SMTP Transport Driver
+ *
+ * Email transport using Nodemailer for SMTP servers.
+ */
+import { formatAddress, generateMessageId } from '../utils.js';
+/**
+ * Default SMTP configuration.
+ */
+const DEFAULT_CONFIG = {
+    port: 587,
+    secure: false,
+    requireTLS: true, // Require TLS by default to prevent MITM downgrade attacks
+    connectionTimeout: 5000,
+    socketTimeout: 5000,
+};
+/**
+ * Create an SMTP mail transport.
+ *
+ * @param config - SMTP configuration
+ * @returns Mail transport implementation
+ *
+ * @example
+ * ```typescript
+ * const transport = await createSmtpTransport({
+ *   host: 'smtp.gmail.com',
+ *   port: 587,
+ *   auth: {
+ *     user: 'user@gmail.com',
+ *     pass: 'app-password',
+ *   },
+ * });
+ *
+ * await transport.send({
+ *   from: { email: 'from@example.com', name: 'App' },
+ *   to: [{ email: 'user@example.com' }],
+ *   subject: 'Hello',
+ *   html: '<h1>Hello World</h1>',
+ * });
+ * ```
+ */
+export async function createSmtpTransport(config) {
+    const options = { ...DEFAULT_CONFIG, ...config };
+    // Dynamic import of nodemailer
+    const nodemailer = await import('nodemailer');
+    // Create transporter
+    const transporter = nodemailer.createTransport({
+        host: config.host,
+        port: options.port,
+        secure: options.secure,
+        requireTLS: options.requireTLS, // Fail if TLS upgrade not possible
+        auth: config.auth,
+        connectionTimeout: options.connectionTimeout,
+        socketTimeout: options.socketTimeout,
+    });
+    /**
+     * Convert EmailAddress array to nodemailer format.
+     */
+    function formatAddresses(addresses) {
+        return addresses.map(formatAddress).join(', ');
+    }
+    /**
+     * Convert attachments to nodemailer format.
+     */
+    function formatAttachments(attachments) {
+        if (!attachments)
+            return [];
+        return attachments.map((att) => ({
+            filename: att.filename,
+            content: att.content,
+            contentType: att.contentType,
+            contentDisposition: att.disposition,
+            cid: att.cid,
+        }));
+    }
+    const transport = {
+        async send(sendOptions) {
+            try {
+                const messageId = generateMessageId();
+                const mailOptions = {
+                    messageId,
+                    from: formatAddress(sendOptions.from),
+                    to: formatAddresses(sendOptions.to),
+                    cc: sendOptions.cc ? formatAddresses(sendOptions.cc) : undefined,
+                    bcc: sendOptions.bcc ? formatAddresses(sendOptions.bcc) : undefined,
+                    replyTo: sendOptions.replyTo ? formatAddress(sendOptions.replyTo) : undefined,
+                    subject: sendOptions.subject,
+                    html: sendOptions.html,
+                    text: sendOptions.text,
+                    attachments: formatAttachments(sendOptions.attachments),
+                    headers: sendOptions.headers,
+                };
+                const result = await transporter.sendMail(mailOptions);
+                return {
+                    success: true,
+                    messageId: result.messageId,
+                };
+            }
+            catch (error) {
+                const errorMessage = error instanceof Error ? error.message : String(error);
+                return {
+                    success: false,
+                    error: errorMessage,
+                };
+            }
+        },
+        async close() {
+            transporter.close();
+        },
+    };
+    return transport;
+}
+/**
+ * SMTP transport driver name.
+ */
+export const DRIVER_NAME = 'smtp';