@veloxts/mail 0.6.51

package/dist/types.d.ts

@@ -0,0 +1,425 @@
+/**
+ * Mail Types
+ *
+ * Type definitions for VeloxTS mail system.
+ */
+import type { ReactElement } from 'react';
+import type { z } from 'zod';
+/**
+ * Available mail transport drivers.
+ */
+export type MailDriver = 'smtp' | 'resend' | 'log';
+/**
+ * Email address with optional name.
+ */
+export interface EmailAddress {
+    /**
+     * Email address (e.g., 'user@example.com').
+     */
+    email: string;
+    /**
+     * Display name (e.g., 'John Doe').
+     */
+    name?: string;
+}
+/**
+ * Email recipient - either string or EmailAddress object.
+ */
+export type Recipient = string | EmailAddress;
+/**
+ * Email attachment.
+ */
+export interface Attachment {
+    /**
+     * Filename to display.
+     */
+    filename: string;
+    /**
+     * File content as Buffer or string.
+     */
+    content: Buffer | string;
+    /**
+     * MIME type (e.g., 'application/pdf').
+     */
+    contentType?: string;
+    /**
+     * Content disposition (attachment or inline).
+     * @default 'attachment'
+     */
+    disposition?: 'attachment' | 'inline';
+    /**
+     * Content ID for inline attachments.
+     */
+    cid?: string;
+}
+/**
+ * Email envelope for sending.
+ */
+export interface MailEnvelope {
+    /**
+     * Recipient(s) - required.
+     */
+    to: Recipient | Recipient[];
+    /**
+     * Carbon copy recipient(s).
+     */
+    cc?: Recipient | Recipient[];
+    /**
+     * Blind carbon copy recipient(s).
+     */
+    bcc?: Recipient | Recipient[];
+    /**
+     * Reply-to address.
+     */
+    replyTo?: Recipient;
+    /**
+     * Email attachments.
+     */
+    attachments?: Attachment[];
+    /**
+     * Custom headers.
+     */
+    headers?: Record<string, string>;
+    /**
+     * Tags for categorization (supported by some providers).
+     */
+    tags?: string[];
+}
+/**
+ * Mail definition configuration.
+ */
+export interface MailDefinitionConfig<TSchema extends z.ZodType> {
+    /**
+     * Unique mail template name (e.g., 'welcome', 'password-reset').
+     */
+    name: string;
+    /**
+     * Zod schema for template data validation.
+     */
+    schema: TSchema;
+    /**
+     * Email subject - can be static string or function of data.
+     */
+    subject: string | ((data: z.infer<TSchema>) => string);
+    /**
+     * React Email template component.
+     */
+    template: (props: z.infer<TSchema>) => ReactElement;
+    /**
+     * Optional plain text version generator.
+     */
+    text?: (data: z.infer<TSchema>) => string;
+    /**
+     * Default from address for this template.
+     */
+    from?: Recipient;
+}
+/**
+ * Mail definition - type-safe email template.
+ */
+export interface MailDefinition<TSchema extends z.ZodType> {
+    /**
+     * Template name.
+     */
+    readonly name: string;
+    /**
+     * Zod schema for data validation.
+     */
+    readonly schema: TSchema;
+    /**
+     * Subject generator.
+     */
+    readonly subject: string | ((data: z.infer<TSchema>) => string);
+    /**
+     * React Email template.
+     */
+    readonly template: (props: z.infer<TSchema>) => ReactElement;
+    /**
+     * Plain text generator.
+     */
+    readonly text?: (data: z.infer<TSchema>) => string;
+    /**
+     * Default from address.
+     */
+    readonly from?: Recipient;
+}
+/**
+ * Options for sending an email.
+ */
+export interface SendMailOptions<TSchema extends z.ZodType> extends MailEnvelope {
+    /**
+     * Template data.
+     */
+    data: z.infer<TSchema>;
+    /**
+     * Override from address.
+     */
+    from?: Recipient;
+}
+/**
+ * Result of sending an email.
+ */
+export interface SendResult {
+    /**
+     * Whether the email was sent successfully.
+     */
+    success: boolean;
+    /**
+     * Message ID from the transport.
+     */
+    messageId?: string;
+    /**
+     * Error message if failed.
+     */
+    error?: string;
+}
+/**
+ * SMTP transport configuration.
+ */
+export interface SmtpConfig {
+    /**
+     * SMTP host.
+     */
+    host: string;
+    /**
+     * SMTP port.
+     * @default 587
+     */
+    port?: number;
+    /**
+     * Use implicit TLS/SSL (port 465).
+     * Set to true for port 465, false for port 587 with STARTTLS.
+     * @default false (uses STARTTLS on port 587)
+     */
+    secure?: boolean;
+    /**
+     * Require TLS connection. When true, the connection will fail if
+     * STARTTLS upgrade is not possible. This prevents MITM downgrade attacks.
+     * Recommended for production use with port 587.
+     * @default true
+     */
+    requireTLS?: boolean;
+    /**
+     * Authentication credentials.
+     */
+    auth?: {
+        user: string;
+        pass: string;
+    };
+    /**
+     * Connection timeout in milliseconds.
+     * @default 5000
+     */
+    connectionTimeout?: number;
+    /**
+     * Socket timeout in milliseconds.
+     * @default 5000
+     */
+    socketTimeout?: number;
+}
+/**
+ * Resend transport configuration.
+ */
+export interface ResendConfig {
+    /**
+     * Resend API key.
+     */
+    apiKey: string;
+}
+/**
+ * Log transport configuration (for development).
+ */
+export interface LogConfig {
+    /**
+     * Whether to output full HTML.
+     * @default false
+     */
+    showHtml?: boolean;
+    /**
+     * Custom logger function.
+     */
+    logger?: (message: string) => void;
+}
+/**
+ * Mail configuration by driver (discriminated union).
+ */
+export type MailConfig = {
+    driver: 'smtp';
+    config: SmtpConfig;
+} | {
+    driver: 'resend';
+    config: ResendConfig;
+} | {
+    driver: 'log';
+    config?: LogConfig;
+};
+/**
+ * Base options shared across all mail configurations.
+ */
+export interface MailBaseOptions {
+    /**
+     * Default from address for all emails.
+     */
+    from?: Recipient;
+    /**
+     * Default reply-to address.
+     */
+    replyTo?: Recipient;
+}
+/**
+ * Mail plugin options with SMTP driver.
+ */
+export interface MailSmtpOptions extends MailBaseOptions {
+    /**
+     * Mail transport driver.
+     */
+    driver: 'smtp';
+    /**
+     * SMTP-specific configuration (required for SMTP driver).
+     */
+    config: SmtpConfig;
+}
+/**
+ * Mail plugin options with Resend driver.
+ */
+export interface MailResendOptions extends MailBaseOptions {
+    /**
+     * Mail transport driver.
+     */
+    driver: 'resend';
+    /**
+     * Resend-specific configuration (required for Resend driver).
+     */
+    config: ResendConfig;
+}
+/**
+ * Mail plugin options with log driver.
+ */
+export interface MailLogOptions extends MailBaseOptions {
+    /**
+     * Mail transport driver.
+     */
+    driver: 'log';
+    /**
+     * Log driver-specific configuration (optional).
+     */
+    config?: LogConfig;
+}
+/**
+ * Mail plugin options with default driver (log).
+ * When no driver is specified, log is used as the default.
+ */
+export interface MailDefaultOptions extends MailBaseOptions {
+    /**
+     * Mail transport driver.
+     * @default 'log'
+     */
+    driver?: undefined;
+    /**
+     * Log driver-specific configuration (default driver).
+     */
+    config?: LogConfig;
+}
+/**
+ * Mail plugin options - discriminated union for type-safe driver configuration.
+ *
+ * The config type automatically narrows based on the selected driver:
+ * - `driver: 'smtp'` - config is SmtpConfig (required)
+ * - `driver: 'resend'` - config is ResendConfig (required)
+ * - `driver: 'log'` - config is LogConfig (optional)
+ * - no driver - defaults to log, config is LogConfig (optional)
+ *
+ * @example
+ * ```typescript
+ * // SMTP driver
+ * mailPlugin({ driver: 'smtp', config: { host: 'smtp.example.com', auth: {...} } });
+ *
+ * // Resend driver
+ * mailPlugin({ driver: 'resend', config: { apiKey: 'key_...' } });
+ *
+ * // Log driver (for development)
+ * mailPlugin({ driver: 'log', config: { showHtml: true } });
+ *
+ * // Default (log)
+ * mailPlugin({ from: { email: 'test@example.com' } });
+ * ```
+ */
+export type MailPluginOptions = MailSmtpOptions | MailResendOptions | MailLogOptions | MailDefaultOptions;
+/**
+ * Mail manager options - same discriminated union for standalone usage.
+ */
+export type MailManagerOptions = MailPluginOptions;
+/**
+ * Mail transport interface for driver implementations.
+ */
+export interface MailTransport {
+    /**
+     * Send an email.
+     */
+    send(options: {
+        from: EmailAddress;
+        to: EmailAddress[];
+        cc?: EmailAddress[];
+        bcc?: EmailAddress[];
+        replyTo?: EmailAddress;
+        subject: string;
+        html: string;
+        text?: string;
+        attachments?: Attachment[];
+        headers?: Record<string, string>;
+        tags?: string[];
+    }): Promise<SendResult>;
+    /**
+     * Close the transport connection.
+     */
+    close(): Promise<void>;
+}
+/**
+ * Rendered email ready for sending.
+ */
+export interface RenderedMail {
+    /**
+     * From address.
+     */
+    from: EmailAddress;
+    /**
+     * To addresses.
+     */
+    to: EmailAddress[];
+    /**
+     * CC addresses.
+     */
+    cc?: EmailAddress[];
+    /**
+     * BCC addresses.
+     */
+    bcc?: EmailAddress[];
+    /**
+     * Reply-to address.
+     */
+    replyTo?: EmailAddress;
+    /**
+     * Email subject.
+     */
+    subject: string;
+    /**
+     * HTML body.
+     */
+    html: string;
+    /**
+     * Plain text body.
+     */
+    text?: string;
+    /**
+     * Attachments.
+     */
+    attachments?: Attachment[];
+    /**
+     * Custom headers.
+     */
+    headers?: Record<string, string>;
+    /**
+     * Tags.
+     */
+    tags?: string[];
+}

package/dist/types.js

@@ -0,0 +1,6 @@
+/**
+ * Mail Types
+ *
+ * Type definitions for VeloxTS mail system.
+ */
+export {};

package/dist/utils.d.ts

@@ -0,0 +1,89 @@
+/**
+ * Mail Utilities
+ *
+ * Helper functions for mail operations.
+ */
+import type { EmailAddress, Recipient } from './types.js';
+/**
+ * Normalize a recipient to EmailAddress format.
+ *
+ * @param recipient - String email or EmailAddress object
+ * @returns Normalized EmailAddress
+ *
+ * @example
+ * ```typescript
+ * normalizeRecipient('user@example.com')
+ * // { email: 'user@example.com' }
+ *
+ * normalizeRecipient({ email: 'user@example.com', name: 'John' })
+ * // { email: 'user@example.com', name: 'John' }
+ *
+ * normalizeRecipient('John Doe <john@example.com>')
+ * // { email: 'john@example.com', name: 'John Doe' }
+ * ```
+ */
+export declare function normalizeRecipient(recipient: Recipient): EmailAddress;
+/**
+ * Normalize multiple recipients.
+ */
+export declare function normalizeRecipients(recipients: Recipient | Recipient[]): EmailAddress[];
+/**
+ * Sanitize a string to prevent email header injection.
+ * Removes newlines, carriage returns, and other control characters.
+ *
+ * @param value - String to sanitize
+ * @returns Sanitized string safe for email headers
+ */
+export declare function sanitizeHeaderValue(value: string): string;
+/**
+ * Format an EmailAddress to string.
+ *
+ * @param address - EmailAddress to format
+ * @returns Formatted string (e.g., "John Doe <john@example.com>")
+ */
+export declare function formatAddress(address: EmailAddress): string;
+/**
+ * Validate an email address format.
+ *
+ * Validates that:
+ * - Local part contains valid characters (alphanumeric, dots, plus, hyphens, underscores)
+ * - Domain contains valid characters (alphanumeric, dots, hyphens)
+ * - TLD has at least 2 characters
+ * - No consecutive dots
+ * - Doesn't start or end with special characters
+ *
+ * @param email - Email address to validate
+ * @returns True if valid
+ */
+export declare function isValidEmail(email: string): boolean;
+/**
+ * Validate a recipient.
+ *
+ * @param recipient - Recipient to validate
+ * @throws Error if recipient is invalid
+ */
+export declare function validateRecipient(recipient: Recipient): void;
+/**
+ * Validate multiple recipients.
+ *
+ * @param recipients - Recipients to validate
+ * @throws Error if any recipient is invalid
+ */
+export declare function validateRecipients(recipients: Recipient | Recipient[]): void;
+/**
+ * Escape HTML entities for safe text output.
+ */
+export declare function escapeHtml(text: string): string;
+/**
+ * Strip HTML tags from string.
+ */
+export declare function stripHtml(html: string): string;
+/**
+ * Generate a unique message ID.
+ */
+export declare function generateMessageId(domain?: string): string;
+/**
+ * Validate mail template name format.
+ * Template names should be kebab-case identifiers.
+ */
+export declare function validateTemplateName(name: string): void;

package/dist/utils.js

@@ -0,0 +1,190 @@
+/**
+ * Mail Utilities
+ *
+ * Helper functions for mail operations.
+ */
+/**
+ * Normalize a recipient to EmailAddress format.
+ *
+ * @param recipient - String email or EmailAddress object
+ * @returns Normalized EmailAddress
+ *
+ * @example
+ * ```typescript
+ * normalizeRecipient('user@example.com')
+ * // { email: 'user@example.com' }
+ *
+ * normalizeRecipient({ email: 'user@example.com', name: 'John' })
+ * // { email: 'user@example.com', name: 'John' }
+ *
+ * normalizeRecipient('John Doe <john@example.com>')
+ * // { email: 'john@example.com', name: 'John Doe' }
+ * ```
+ */
+export function normalizeRecipient(recipient) {
+    if (typeof recipient === 'object') {
+        return recipient;
+    }
+    // Parse "Name <email@example.com>" format
+    const match = recipient.match(/^(.+?)\s*<(.+?)>$/);
+    if (match) {
+        return {
+            name: match[1].trim(),
+            email: match[2].trim(),
+        };
+    }
+    return { email: recipient };
+}
+/**
+ * Normalize multiple recipients.
+ */
+export function normalizeRecipients(recipients) {
+    const recipientArray = Array.isArray(recipients) ? recipients : [recipients];
+    return recipientArray.map(normalizeRecipient);
+}
+/**
+ * Sanitize a string to prevent email header injection.
+ * Removes newlines, carriage returns, and other control characters.
+ *
+ * @param value - String to sanitize
+ * @returns Sanitized string safe for email headers
+ */
+export function sanitizeHeaderValue(value) {
+    // Remove newlines, carriage returns, tabs, and other control characters
+    // that could be used for header injection attacks.
+    // Uses character-by-character filtering to avoid regex lint warnings.
+    let result = '';
+    for (const char of value) {
+        const code = char.charCodeAt(0);
+        // Replace control characters (0x00-0x1f) and DEL (0x7f) with space
+        if (code <= 0x1f || code === 0x7f) {
+            result += ' ';
+        }
+        else {
+            result += char;
+        }
+    }
+    return result.trim();
+}
+/**
+ * Format an EmailAddress to string.
+ *
+ * @param address - EmailAddress to format
+ * @returns Formatted string (e.g., "John Doe <john@example.com>")
+ */
+export function formatAddress(address) {
+    if (address.name) {
+        // Sanitize name to prevent header injection attacks
+        const sanitizedName = sanitizeHeaderValue(address.name);
+        return `${sanitizedName} <${address.email}>`;
+    }
+    return address.email;
+}
+/**
+ * Validate an email address format.
+ *
+ * Validates that:
+ * - Local part contains valid characters (alphanumeric, dots, plus, hyphens, underscores)
+ * - Domain contains valid characters (alphanumeric, dots, hyphens)
+ * - TLD has at least 2 characters
+ * - No consecutive dots
+ * - Doesn't start or end with special characters
+ *
+ * @param email - Email address to validate
+ * @returns True if valid
+ */
+export function isValidEmail(email) {
+    if (!email || typeof email !== 'string') {
+        return false;
+    }
+    // More robust email validation:
+    // - Local part: letters, numbers, dots, plus, hyphens, underscores (no consecutive dots)
+    // - @ symbol
+    // - Domain: letters, numbers, dots, hyphens (no consecutive dots)
+    // - TLD: at least 2 letters
+    const emailRegex = /^[a-zA-Z0-9](?:[a-zA-Z0-9._+-]*[a-zA-Z0-9])?@[a-zA-Z0-9](?:[a-zA-Z0-9.-]*[a-zA-Z0-9])?\.[a-zA-Z]{2,}$/;
+    // Additional check: no consecutive dots anywhere
+    if (email.includes('..')) {
+        return false;
+    }
+    return emailRegex.test(email);
+}
+/**
+ * Validate a recipient.
+ *
+ * @param recipient - Recipient to validate
+ * @throws Error if recipient is invalid
+ */
+export function validateRecipient(recipient) {
+    const normalized = normalizeRecipient(recipient);
+    if (!normalized.email) {
+        throw new Error('Recipient email is required');
+    }
+    if (!isValidEmail(normalized.email)) {
+        throw new Error(`Invalid email address: ${normalized.email}`);
+    }
+}
+/**
+ * Validate multiple recipients.
+ *
+ * @param recipients - Recipients to validate
+ * @throws Error if any recipient is invalid
+ */
+export function validateRecipients(recipients) {
+    const recipientArray = Array.isArray(recipients) ? recipients : [recipients];
+    if (recipientArray.length === 0) {
+        throw new Error('At least one recipient is required');
+    }
+    for (const recipient of recipientArray) {
+        validateRecipient(recipient);
+    }
+}
+/**
+ * Escape HTML entities for safe text output.
+ */
+export function escapeHtml(text) {
+    const htmlEscapes = {
+        '&': '&amp;',
+        '<': '&lt;',
+        '>': '&gt;',
+        '"': '&quot;',
+        "'": '&#39;',
+    };
+    return text.replace(/[&<>"']/g, (char) => htmlEscapes[char]);
+}
+/**
+ * Strip HTML tags from string.
+ */
+export function stripHtml(html) {
+    return html
+        .replace(/<[^>]*>/g, '') // Remove HTML tags
+        .replace(/&nbsp;/g, ' ') // Replace &nbsp; with space
+        .replace(/&amp;/g, '&') // Decode &amp;
+        .replace(/&lt;/g, '<') // Decode &lt;
+        .replace(/&gt;/g, '>') // Decode &gt;
+        .replace(/&quot;/g, '"') // Decode &quot;
+        .replace(/&#39;/g, "'") // Decode &#39;
+        .replace(/\s+/g, ' ') // Collapse whitespace
+        .trim();
+}
+/**
+ * Generate a unique message ID.
+ */
+export function generateMessageId(domain) {
+    const timestamp = Date.now().toString(36);
+    const random = Math.random().toString(36).substring(2, 10);
+    const domainPart = domain ?? 'veloxts.local';
+    return `<${timestamp}.${random}@${domainPart}>`;
+}
+/**
+ * Validate mail template name format.
+ * Template names should be kebab-case identifiers.
+ */
+export function validateTemplateName(name) {
+    if (!name || typeof name !== 'string') {
+        throw new Error('Template name must be a non-empty string');
+    }
+    if (!/^[a-z][a-z0-9]*(-[a-z][a-z0-9]*)*$/.test(name)) {
+        throw new Error(`Invalid template name: ${name}. Use kebab-case format (e.g., 'welcome', 'password-reset')`);
+    }
+}