@rapidd/core 2.1.0

package/src/utils/Mailer.ts

@@ -0,0 +1,348 @@
+import nodemailer from 'nodemailer';
+import ejs from 'ejs';
+import fs from 'fs';
+import path from 'path';
+import { LanguageDict } from '../core/i18n';
+
+// ── Types ────────────────────────────────────────────────────────────────────
+
+export interface EmailConfig {
+    host: string;
+    port: number;
+    secure?: boolean;
+    user: string;
+    password: string;
+    from?: string;
+    name?: string;
+}
+
+export interface EmailAttachment {
+    filename?: string;
+    content?: string | Buffer;
+    path?: string;
+    href?: string;
+    contentType?: string;
+    encoding?: string;
+    cid?: string;
+}
+
+export interface EmailOptions {
+    to: string | string[];
+    subject: string;
+    html?: string;
+    text?: string;
+    cc?: string | string[];
+    bcc?: string | string[];
+    replyTo?: string;
+    attachments?: EmailAttachment[];
+    headers?: Record<string, string>;
+}
+
+export interface EmailResult {
+    success: boolean;
+    messageId?: string;
+    error?: Error;
+}
+
+// ── Configuration ────────────────────────────────────────────────────────────
+
+let _config: { emails?: Record<string, EmailConfig> } = { emails: {} };
+let _configLoaded = false;
+
+function getConfig(): { emails?: Record<string, EmailConfig> } {
+    if (!_configLoaded) {
+        try {
+            _config = require(path.join(process.cwd(), 'config', 'app.json'));
+        } catch {
+            _config = { emails: {} };
+        }
+        _configLoaded = true;
+    }
+    return _config;
+}
+
+function getEmailConfig(configKey: string): EmailConfig {
+    const config = getConfig();
+
+    if (!config.emails || typeof config.emails !== 'object') {
+        throw new Error('Email configuration not found in config/app.json');
+    }
+
+    const emailConfig = config.emails[configKey];
+    if (!emailConfig) {
+        const available = Object.keys(config.emails).join(', ') || 'none';
+        throw new Error(`Email config '${configKey}' not found. Available: ${available}`);
+    }
+
+    const required: (keyof EmailConfig)[] = ['host', 'port', 'user', 'password'];
+    const missing = required.filter(field => !emailConfig[field]);
+
+    if (missing.length > 0) {
+        throw new Error(`Email config '${configKey}' missing required fields: ${missing.join(', ')}`);
+    }
+
+    return emailConfig;
+}
+
+function createTransporter(config: EmailConfig) {
+    return nodemailer.createTransport({
+        host: config.host,
+        port: config.port,
+        secure: config.secure ?? config.port === 465,
+        auth: {
+            user: config.user,
+            pass: config.password
+        },
+        tls: {
+            rejectUnauthorized: process.env.NODE_ENV === 'production'
+        },
+        pool: true,
+        maxConnections: 5,
+        maxMessages: 100
+    });
+}
+
+// ── Template Rendering ──────────────────────────────────────────────────────
+
+const TEMPLATES_PATH = path.join(process.cwd(), 'templates', 'email');
+const LAYOUTS_PATH = path.join(process.cwd(), 'templates', 'layouts');
+const templateCache = new Map<string, string>();
+
+function loadTemplate(name: string): string {
+    if (templateCache.has(name)) {
+        return templateCache.get(name)!;
+    }
+
+    const filePath = path.join(TEMPLATES_PATH, `${name}.ejs`);
+    if (!fs.existsSync(filePath)) {
+        throw new Error(`Email template '${name}' not found at ${filePath}`);
+    }
+
+    const content = fs.readFileSync(filePath, 'utf-8');
+    templateCache.set(name, content);
+    return content;
+}
+
+function loadLayout(name: string): string | null {
+    const cacheKey = `layout:${name}`;
+    if (templateCache.has(cacheKey)) {
+        return templateCache.get(cacheKey)!;
+    }
+
+    const filePath = path.join(LAYOUTS_PATH, `${name}.ejs`);
+    if (!fs.existsSync(filePath)) {
+        return null;
+    }
+
+    const content = fs.readFileSync(filePath, 'utf-8');
+    templateCache.set(cacheKey, content);
+    return content;
+}
+
+function renderTemplate(name: string, data: Record<string, unknown> = {}, layout: string | false = 'email', language?: string): string {
+    const template = loadTemplate(name);
+
+    // Inject __() translation helper into template data
+    const lang = language || (data.language as string) || undefined;
+    const templateData = {
+        ...data,
+        __: (key: string, params?: Record<string, unknown>) => LanguageDict.get(key, params || null, lang || null),
+    };
+
+    const body = ejs.render(template, templateData, { filename: path.join(TEMPLATES_PATH, `${name}.ejs`) });
+
+    // Wrap in layout (default: 'email', pass false to skip)
+    if (layout !== false) {
+        const layoutContent = loadLayout(layout);
+        if (layoutContent) {
+            return ejs.render(layoutContent, { ...templateData, body }, { filename: path.join(LAYOUTS_PATH, `${layout}.ejs`) });
+        }
+    }
+
+    return body;
+}
+
+// ── Validation ──────────────────────────────────────────────────────────────
+
+function validateEmail(email: string): boolean {
+    return /^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(email);
+}
+
+function validateOptions(options: EmailOptions): void {
+    if (!options.to) {
+        throw new Error('Recipient (to) is required');
+    }
+
+    if (!options.subject) {
+        throw new Error('Subject is required');
+    }
+
+    if (!options.html && !options.text) {
+        throw new Error('Email body (html or text) is required');
+    }
+
+    const recipients = Array.isArray(options.to) ? options.to : [options.to];
+    for (const email of recipients) {
+        if (!validateEmail(email)) {
+            throw new Error(`Invalid email address: ${email}`);
+        }
+    }
+}
+
+// ── Main API ─────────────────────────────────────────────────────────────────
+
+/**
+ * Config-driven email client with multiple SMTP profiles.
+ *
+ * @example
+ * // Simple email
+ * await Mailer.send('default', {
+ *     to: 'user@example.com',
+ *     subject: 'Hello',
+ *     html: '<h1>Welcome!</h1>'
+ * });
+ *
+ * @example
+ * // With attachments
+ * await Mailer.send('support', {
+ *     to: ['user1@example.com', 'user2@example.com'],
+ *     subject: 'Invoice',
+ *     html: '<p>Please find your invoice attached.</p>',
+ *     attachments: [
+ *         { filename: 'invoice.pdf', path: './invoice.pdf' }
+ *     ]
+ * });
+ *
+ * @example
+ * // Render EJS template and send
+ * await Mailer.sendTemplate('default', 'confirmation', {
+ *     to: 'user@example.com',
+ *     subject: 'Confirm your email',
+ *     data: { name: 'John', confirmationUrl: 'https://...' }
+ * });
+ *
+ * @example
+ * // Render template without sending
+ * const html = Mailer.render('resetPassword', { name: 'John', resetUrl: '...' });
+ */
+export const Mailer = {
+    /**
+     * Send a single email using a configured SMTP profile
+     */
+    async send(configKey: string, options: EmailOptions): Promise<EmailResult> {
+        try {
+            const config = getEmailConfig(configKey);
+            validateOptions(options);
+
+            const transporter = createTransporter(config);
+
+            const mailOptions = {
+                from: config.from || `"${config.name || 'No Reply'}" <${config.user}>`,
+                to: options.to,
+                subject: options.subject,
+                html: options.html,
+                text: options.text,
+                cc: options.cc,
+                bcc: options.bcc,
+                replyTo: options.replyTo,
+                attachments: options.attachments,
+                headers: options.headers
+            };
+
+            const info = await transporter.sendMail(mailOptions);
+            transporter.close();
+
+            return {
+                success: true,
+                messageId: info.messageId
+            };
+        } catch (error) {
+            return {
+                success: false,
+                error: error as Error
+            };
+        }
+    },
+
+    /**
+     * Send multiple emails in parallel
+     */
+    async sendBatch(
+        configKey: string,
+        emails: EmailOptions[]
+    ): Promise<EmailResult[]> {
+        const results = await Promise.allSettled(
+            emails.map(options => this.send(configKey, options))
+        );
+
+        return results.map((result) => {
+            if (result.status === 'fulfilled') {
+                return result.value;
+            }
+            return {
+                success: false,
+                error: result.reason
+            };
+        });
+    },
+
+    /**
+     * Verify SMTP connection for a configuration
+     */
+    async verify(configKey: string): Promise<boolean> {
+        try {
+            const config = getEmailConfig(configKey);
+            const transporter = createTransporter(config);
+
+            await transporter.verify();
+            transporter.close();
+
+            return true;
+        } catch {
+            return false;
+        }
+    },
+
+    /**
+     * Render an EJS email template from templates/email/
+     * Templates have access to __() for translations: <%= __('signIn') %>
+     * @param layout - Layout name from templates/layouts/ (default: 'email'), or false to skip layout
+     * @param language - Language code for translations (e.g. 'de_DE'), defaults to 'en_US'
+     */
+    render(template: string, data: Record<string, unknown> = {}, layout: string | false = 'email', language?: string): string {
+        return renderTemplate(template, data, layout, language);
+    },
+
+    /**
+     * Render an EJS template and send it as an email
+     * Templates have access to __() for translations: <%= __('signIn') %>
+     * @param options.layout - Layout name from templates/layouts/ (default: 'email'), or false to skip layout
+     * @param options.language - Language code for translations (e.g. 'de_DE'), defaults to 'en_US'
+     */
+    async sendTemplate(
+        configKey: string,
+        template: string,
+        options: { to: string | string[]; subject: string; data?: Record<string, unknown>; layout?: string | false; language?: string } & Omit<EmailOptions, 'html'>
+    ): Promise<EmailResult> {
+        const { data = {}, layout = 'email', language, ...emailOptions } = options;
+        const html = renderTemplate(template, { ...data, subject: options.subject }, layout, language);
+        return this.send(configKey, { ...emailOptions, html });
+    },
+
+    /**
+     * Clear the template cache (e.g. after editing templates in dev)
+     */
+    clearTemplateCache(): void {
+        templateCache.clear();
+    },
+
+    /**
+     * List available email configurations
+     */
+    listConfigs(): string[] {
+        const config = getConfig();
+        return Object.keys(config.emails || {});
+    }
+};
+
+export default Mailer;

package/src/utils/index.ts

@@ -0,0 +1,25 @@
+export { ApiClient, ApiClientError } from './ApiClient';
+export type { ServiceConfig, EndpointConfig, AuthConfig, RequestOptions, ApiResponse } from './ApiClient';
+
+export { Mailer } from './Mailer';
+export type { EmailConfig, EmailOptions, EmailAttachment, EmailResult } from './Mailer';
+
+export const env = {
+    isProduction: () => process.env.NODE_ENV === 'production',
+    isDevelopment: () => __filename.endsWith('.ts') || process.env.NODE_ENV === 'development',
+    isTest: () => process.env.NODE_ENV === 'test',
+    current: () => process.env.NODE_ENV || 'development',
+
+    get: <T extends string | number | boolean>(key: string, defaultValue: T): T => {
+        const value = process.env[key];
+        if (value === undefined) return defaultValue;
+
+        if (typeof defaultValue === 'number') {
+            return parseInt(value, 10) as T;
+        }
+        if (typeof defaultValue === 'boolean') {
+            return (value.toLowerCase() === 'true') as T;
+        }
+        return value as T;
+    }
+};

package/templates/email/example.ejs

@@ -0,0 +1,17 @@
+<p>Hi <%= name %>,</p>
+
+<p>Welcome to <strong><%= appName %></strong>. Your account has been created successfully.</p>
+
+<% if (locals.activationLink) { %>
+<p>Please verify your email address to get started:</p>
+<p style="text-align: center; margin: 32px 0;">
+    <a href="<%= activationLink %>" class="btn">Verify Email</a>
+</p>
+<% } %>
+
+<p>If you have any questions, feel free to reach out to our support team.</p>
+
+<p>
+    Best regards,<br>
+    The <%= appName %> Team
+</p>

package/templates/layouts/email.ejs

@@ -0,0 +1,35 @@
+<!DOCTYPE html>
+<html lang="en">
+<head>
+    <meta charset="UTF-8">
+    <meta name="viewport" content="width=device-width, initial-scale=1.0">
+    <title><%= subject %></title>
+    <style>
+        body { margin: 0; padding: 0; background-color: #f4f4f7; font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, Helvetica, Arial, sans-serif; }
+        .container { max-width: 600px; margin: 0 auto; padding: 40px 20px; }
+        .card { background: #ffffff; border-radius: 8px; padding: 40px; box-shadow: 0 1px 3px rgba(0,0,0,0.08); }
+        .header { text-align: center; margin-bottom: 32px; }
+        .header h1 { margin: 0; font-size: 24px; color: #1a1a2e; }
+        .content { color: #333; font-size: 16px; line-height: 1.6; }
+        .content p { margin: 0 0 16px; }
+        .btn { display: inline-block; padding: 12px 32px; background-color: #1a1a2e; color: #ffffff; text-decoration: none; border-radius: 6px; font-weight: 600; font-size: 14px; }
+        .footer { text-align: center; margin-top: 32px; font-size: 13px; color: #999; }
+    </style>
+</head>
+<body>
+    <div class="container">
+        <div class="card">
+            <div class="header">
+                <% if (locals.logoUrl) { %><img src="<%= logoUrl %>" alt="" height="40" style="margin-bottom: 16px;"><% } %>
+                <h1><%= subject %></h1>
+            </div>
+            <div class="content">
+                <%- body %>
+            </div>
+        </div>
+        <div class="footer">
+            <% if (locals.footerText) { %><%= footerText %><% } %>
+        </div>
+    </div>
+</body>
+</html>

package/tsconfig.json

@@ -0,0 +1,33 @@
+{
+  "compilerOptions": {
+    "target": "ES2024",
+    "module": "commonjs",
+    "moduleResolution": "node",
+    "lib": ["ES2024"],
+    "outDir": "dist",
+    "rootDir": ".",
+    "strict": true,
+    "esModuleInterop": true,
+    "declaration": true,
+    "declarationMap": true,
+    "sourceMap": true,
+    "skipLibCheck": true,
+    "forceConsistentCasingInFileNames": true,
+    "resolveJsonModule": true,
+    "noUnusedLocals": false,
+    "noUnusedParameters": false,
+    "noImplicitReturns": true,
+    "noFallthroughCasesInSwitch": true
+  },
+  "include": [
+    "src/**/*.ts",
+    "main.ts",
+    "routes/**/*.ts"
+  ],
+  "exclude": [
+    "node_modules",
+    "dist",
+    "__test__",
+    "**/*.js"
+  ]
+}