webspresso 0.0.99 → 0.0.101

package/core/mail/mailable.js

@@ -0,0 +1,250 @@
+/**
+ * Declarative Mailable Base Class (AdonisJS & Laravel-inspired)
+ * @module core/mail/mailable
+ */
+
+/**
+ * Base class for declarative, reusable email templates
+ */
+class Mailable {
+  constructor() {
+    this.message = {
+      to: [],
+      from: null,
+      replyTo: null,
+      cc: [],
+      bcc: [],
+      subject: '',
+      template: null,
+      html: null,
+      text: null,
+      mjml: null,
+      data: {},
+      attachments: [],
+      headers: {},
+    };
+  }
+
+  /**
+   * Add recipient(s)
+   * @param {string|string[]|Object} recipient
+   * @param {string} [name]
+   * @returns {this}
+   */
+  to(recipient, name) {
+    if (Array.isArray(recipient)) {
+      this.message.to.push(...recipient);
+    } else if (name && typeof recipient === 'string') {
+      this.message.to.push({ address: recipient, name });
+    } else if (recipient) {
+      this.message.to.push(recipient);
+    }
+    return this;
+  }
+
+  /**
+   * Set sender address
+   * @param {string} address
+   * @param {string} [name]
+   * @returns {this}
+   */
+  from(address, name) {
+    this.message.from = name ? { address, name } : address;
+    return this;
+  }
+
+  /**
+   * Set reply-to address
+   * @param {string} address
+   * @returns {this}
+   */
+  replyTo(address) {
+    this.message.replyTo = address;
+    return this;
+  }
+
+  /**
+   * Add CC recipient(s)
+   * @param {string|string[]} recipient
+   * @returns {this}
+   */
+  cc(recipient) {
+    if (Array.isArray(recipient)) {
+      this.message.cc.push(...recipient);
+    } else if (recipient) {
+      this.message.cc.push(recipient);
+    }
+    return this;
+  }
+
+  /**
+   * Add BCC recipient(s)
+   * @param {string|string[]} recipient
+   * @returns {this}
+   */
+  bcc(recipient) {
+    if (Array.isArray(recipient)) {
+      this.message.bcc.push(...recipient);
+    } else if (recipient) {
+      this.message.bcc.push(recipient);
+    }
+    return this;
+  }
+
+  /**
+   * Set email subject line
+   * @param {string} subj
+   * @returns {this}
+   */
+  subject(subj) {
+    this.message.subject = subj;
+    return this;
+  }
+
+  /**
+   * Set template name / identifier
+   * @param {string} tplName
+   * @returns {this}
+   */
+  template(tplName) {
+    this.message.template = tplName;
+    return this;
+  }
+
+  /**
+   * Set raw HTML body
+   * @param {string} htmlContent
+   * @returns {this}
+   */
+  html(htmlContent) {
+    this.message.html = htmlContent;
+    return this;
+  }
+
+  /**
+   * Set plain text body
+   * @param {string} textContent
+   * @returns {this}
+   */
+  text(textContent) {
+    this.message.text = textContent;
+    return this;
+  }
+
+  /**
+   * Set MJML template string
+   * @param {string} mjmlContent
+   * @returns {this}
+   */
+  mjml(mjmlContent) {
+    this.message.mjml = mjmlContent;
+    return this;
+  }
+
+  /**
+   * Set template view and/or view data
+   * @param {string|Object} templateOrData
+   * @param {Object} [data]
+   * @returns {this}
+   */
+  view(templateOrData, data) {
+    if (typeof templateOrData === 'string') {
+      this.message.template = templateOrData;
+      if (data && typeof data === 'object') {
+        Object.assign(this.message.data, data);
+      }
+    } else if (templateOrData && typeof templateOrData === 'object') {
+      Object.assign(this.message.data, templateOrData);
+    }
+    return this;
+  }
+
+  /**
+   * Assign template data
+   * @param {string|Object} keyOrObj
+   * @param {*} [value]
+   * @returns {this}
+   */
+  data(keyOrObj, value) {
+    if (typeof keyOrObj === 'string') {
+      this.message.data[keyOrObj] = value;
+    } else if (keyOrObj && typeof keyOrObj === 'object') {
+      Object.assign(this.message.data, keyOrObj);
+    }
+    return this;
+  }
+
+  /**
+   * Add attachment
+   * @param {Object} attachment
+   * @returns {this}
+   */
+  attach(attachment) {
+    if (attachment) {
+      this.message.attachments.push(attachment);
+    }
+    return this;
+  }
+
+  /**
+   * Set custom header
+   * @param {string} key
+   * @param {string} value
+   * @returns {this}
+   */
+  header(key, value) {
+    this.message.headers[key] = value;
+    return this;
+  }
+
+  /**
+   * Subclass hook executed before sending
+   */
+  prepare() {}
+
+  /**
+   * Subclass hook executed to build email definition
+   */
+  build() {}
+
+  /**
+   * Convert to normalized message payload object
+   * @returns {Object}
+   */
+  toMessage() {
+    // Copy any class field declarations (e.g. `template = 'welcome'`, `subjectText = 'Hi'`)
+    if (!this.message.template && typeof this.template === 'string') {
+      this.message.template = this.template;
+    }
+    if (!this.message.subject && (this.subjectText || this._subject)) {
+      this.message.subject = this.subjectText || this._subject;
+    }
+    if (!this.message.from && this.fromAddress) {
+      this.message.from = this.fromAddress;
+    }
+
+    this.prepare();
+    this.build();
+
+    const msg = {
+      ...this.message,
+      data: { ...this.message.data },
+      attachments: [...this.message.attachments],
+      headers: { ...this.message.headers },
+    };
+
+    if (Array.isArray(msg.to)) {
+      if (msg.to.length === 1) {
+        msg.to = msg.to[0];
+      } else if (msg.to.length === 0) {
+        msg.to = null;
+      }
+    }
+
+    return msg;
+  }
+}
+
+module.exports = {
+  Mailable,
+};

package/core/mail/mailer.js

@@ -0,0 +1,184 @@
+/**
+ * Core Mailer Service (AdonisJS & Django-inspired)
+ * @module core/mail/mailer
+ */
+
+const { Mailable } = require('./mailable');
+const { resolveTransport, MemoryTransport } = require('./transports');
+
+/**
+ * Mailer service for managing email dispatch, previewing, and outbox tracking
+ */
+class Mailer {
+  /**
+   * @param {Object} [options={}]
+   * @param {Object} [options.transport] - Custom transport or options for resolveTransport
+   * @param {Object} [options.defaults] - Default from/replyTo
+   * @param {Function} [options.renderer] - Template renderer function (template, data) => Promise<{ html, text }>
+   * @param {Object} [options.events] - Optional event emitter / signal dispatcher
+   * @param {Function} [options.logger] - Optional logger
+   */
+  constructor(options = {}) {
+    this.options = options;
+    this.transport = resolveTransport(options);
+    this.defaults = options.defaults || {};
+    this.renderer = options.renderer || null;
+    this.events = options.events || null;
+    this.logger = options.logger || console;
+  }
+
+  /**
+   * Send an email using a Mailable instance or raw options object
+   * @param {Mailable|Object} mailableOrOptions
+   * @returns {Promise<Object>}
+   */
+  async send(mailableOrOptions) {
+    if (!mailableOrOptions) {
+      throw new Error('mailableOrOptions is required to send email');
+    }
+
+    const msg = mailableOrOptions instanceof Mailable
+      ? mailableOrOptions.toMessage()
+      : { ...mailableOrOptions };
+
+    if (!msg.to || (Array.isArray(msg.to) && msg.to.length === 0)) {
+      throw new Error('Email recipient "to" is required');
+    }
+    if (!msg.subject) {
+      throw new Error('Email "subject" is required');
+    }
+
+    // Default from
+    if (!msg.from && this.defaults.from) {
+      msg.from = this.defaults.from;
+    }
+    if (!msg.replyTo && this.defaults.replyTo) {
+      msg.replyTo = this.defaults.replyTo;
+    }
+
+    // Render template if template identifier provided and renderer configured
+    if (msg.template && this.renderer && typeof this.renderer === 'function') {
+      const rendered = await this.renderer(msg.template, msg.data || {});
+      if (rendered) {
+        msg.html = rendered.html || msg.html;
+        msg.text = rendered.text || msg.text;
+      }
+    }
+
+    // Fallback simple text from HTML if text not provided
+    if (!msg.text && typeof msg.html === 'string') {
+      msg.text = msg.html.replace(/<[^>]+>/g, ' ').replace(/\s+/g, ' ').trim();
+    }
+
+    try {
+      const result = await this.transport.sendMail(msg);
+
+      if (this.events && typeof this.events.emit === 'function') {
+        this.events.emit('mail:sent', { message: msg, result });
+      }
+
+      return {
+        ok: true,
+        messageId: result.messageId,
+        response: result.response,
+        accepted: result.accepted,
+        rejected: result.rejected,
+        result,
+      };
+    } catch (err) {
+      if (this.events && typeof this.events.emit === 'function') {
+        this.events.emit('mail:failed', { message: msg, error: err });
+      }
+      throw err;
+    }
+  }
+
+  /**
+   * Preview a Mailable without sending
+   * @param {Mailable|Object} mailableOrOptions
+   * @returns {Promise<Object>}
+   */
+  async preview(mailableOrOptions) {
+    if (!mailableOrOptions) {
+      throw new Error('mailableOrOptions is required to preview email');
+    }
+
+    const msg = mailableOrOptions instanceof Mailable
+      ? mailableOrOptions.toMessage()
+      : { ...mailableOrOptions };
+
+    if (msg.template && this.renderer && typeof this.renderer === 'function') {
+      const rendered = await this.renderer(msg.template, msg.data || {});
+      if (rendered) {
+        msg.html = rendered.html || msg.html;
+        msg.text = rendered.text || msg.text;
+      }
+    }
+
+    return {
+      to: msg.to,
+      from: msg.from || this.defaults.from,
+      subject: msg.subject,
+      html: msg.html || '',
+      text: msg.text || '',
+      data: msg.data || {},
+      attachments: msg.attachments || [],
+      headers: msg.headers || {},
+    };
+  }
+
+  /**
+   * Get messages from in-memory outbox (if MemoryTransport active)
+   * @returns {Array<Object>}
+   */
+  getOutbox() {
+    if (this.transport && typeof this.transport.getOutbox === 'function') {
+      return this.transport.getOutbox();
+    }
+    return [];
+  }
+
+  /**
+   * Clear in-memory outbox
+   */
+  clearOutbox() {
+    if (this.transport && typeof this.transport.clearOutbox === 'function') {
+      this.transport.clearOutbox();
+    }
+  }
+
+  /**
+   * Get latest sent message from outbox
+   * @returns {Object|null}
+   */
+  lastMessage() {
+    if (this.transport && typeof this.transport.lastMessage === 'function') {
+      return this.transport.lastMessage();
+    }
+    return null;
+  }
+
+  /**
+   * Check connection/transport health
+   */
+  async verify() {
+    if (this.transport && typeof this.transport.verify === 'function') {
+      return this.transport.verify();
+    }
+    return true;
+  }
+}
+
+/**
+ * Factory to create Mailer instance
+ * @param {Object} options
+ * @returns {Mailer}
+ */
+function createMailer(options = {}) {
+  return new Mailer(options);
+}
+
+module.exports = {
+  Mailer,
+  createMailer,
+};

package/core/mail/transports.js

@@ -0,0 +1,238 @@
+/**
+ * Mail Transports / Backends (Django Email Backends & AdonisJS-inspired)
+ * @module core/mail/transports
+ */
+
+const crypto = require('crypto');
+const fs = require('fs');
+const path = require('path');
+
+let nodemailer;
+try {
+  nodemailer = require('nodemailer');
+} catch {
+  nodemailer = null;
+}
+
+/**
+ * In-Memory Transport for testing & local development dev inbox (Django MemoryEmailBackend)
+ */
+class MemoryTransport {
+  constructor(options = {}) {
+    this.name = 'memory';
+    this.outbox = [];
+    this.options = options;
+  }
+
+  /**
+   * Send mail into in-memory outbox array
+   * @param {Object} mailOptions
+   * @returns {Promise<Object>}
+   */
+  async sendMail(mailOptions) {
+    const id = mailOptions.messageId || `msg_${Date.now()}_${crypto.randomBytes(4).toString('hex')}`;
+    const sentEntry = {
+      id,
+      messageId: id,
+      ...mailOptions,
+      sentAt: new Date(),
+    };
+
+    this.outbox.push(sentEntry);
+
+    return {
+      messageId: id,
+      accepted: Array.isArray(mailOptions.to) ? mailOptions.to : [mailOptions.to],
+      rejected: [],
+      response: '250 OK: Message stored in MemoryTransport outbox',
+    };
+  }
+
+  getOutbox() {
+    return [...this.outbox];
+  }
+
+  clearOutbox() {
+    this.outbox = [];
+  }
+
+  lastMessage() {
+    return this.outbox.length > 0 ? this.outbox[this.outbox.length - 1] : null;
+  }
+
+  findById(id) {
+    return this.outbox.find((msg) => msg.id === id || msg.messageId === id) || null;
+  }
+
+  async verify() {
+    return true;
+  }
+}
+
+/**
+ * Console Transport for development inspection (Django ConsoleEmailBackend)
+ */
+class ConsoleTransport {
+  constructor(options = {}) {
+    this.name = 'console';
+    this.logger = options.logger || console;
+  }
+
+  async sendMail(mailOptions) {
+    const id = `console_${Date.now()}_${crypto.randomBytes(3).toString('hex')}`;
+    const border = '='.repeat(60);
+
+    this.logger.log(`\n${border}`);
+    this.logger.log(`📧 [EMAIL SENT VIA CONSOLE TRANSPORT] (${id})`);
+    this.logger.log(`From:    ${mailOptions.from || '(default)'}`);
+    this.logger.log(`To:      ${Array.isArray(mailOptions.to) ? mailOptions.to.join(', ') : mailOptions.to}`);
+    if (mailOptions.cc) this.logger.log(`Cc:      ${mailOptions.cc}`);
+    if (mailOptions.bcc) this.logger.log(`Bcc:     ${mailOptions.bcc}`);
+    this.logger.log(`Subject: ${mailOptions.subject}`);
+    this.logger.log(`Date:    ${new Date().toISOString()}`);
+    this.logger.log('-'.repeat(60));
+    if (mailOptions.text) {
+      this.logger.log('--- Plain Text ---');
+      this.logger.log(mailOptions.text);
+    }
+    if (mailOptions.html) {
+      this.logger.log('--- HTML Content ---');
+      this.logger.log(mailOptions.html.length > 300 ? `${mailOptions.html.slice(0, 300)}... (truncated)` : mailOptions.html);
+    }
+    this.logger.log(`${border}\n`);
+
+    return {
+      messageId: id,
+      accepted: Array.isArray(mailOptions.to) ? mailOptions.to : [mailOptions.to],
+      rejected: [],
+      response: '250 OK: Logged to console',
+    };
+  }
+
+  async verify() {
+    return true;
+  }
+}
+
+/**
+ * File-based Transport for offline inspection (Django FileEmailBackend)
+ */
+class FileTransport {
+  constructor(options = {}) {
+    this.name = 'file';
+    this.dir = options.dir || path.join(process.cwd(), '.cache', 'emails');
+    if (!fs.existsSync(this.dir)) {
+      try {
+        fs.mkdirSync(this.dir, { recursive: true });
+      } catch {
+        // ignore
+      }
+    }
+  }
+
+  async sendMail(mailOptions) {
+    const id = `mail_${Date.now()}_${crypto.randomBytes(4).toString('hex')}`;
+    const filePath = path.join(this.dir, `${id}.json`);
+    const data = {
+      id,
+      ...mailOptions,
+      sentAt: new Date().toISOString(),
+    };
+
+    try {
+      fs.writeFileSync(filePath, JSON.stringify(data, null, 2), 'utf-8');
+    } catch (err) {
+      console.warn('[FileTransport] Failed to write file:', err.message);
+    }
+
+    return {
+      messageId: id,
+      accepted: Array.isArray(mailOptions.to) ? mailOptions.to : [mailOptions.to],
+      rejected: [],
+      filePath,
+      response: `250 OK: Written to ${filePath}`,
+    };
+  }
+
+  async verify() {
+    return fs.existsSync(this.dir);
+  }
+}
+
+/**
+ * Build SMTP config from env vars
+ * @returns {Object|null}
+ */
+function smtpFromEnv() {
+  const host = process.env.SMTP_HOST;
+  if (!host) return null;
+
+  const port = parseInt(process.env.SMTP_PORT || '587', 10);
+  const secure = process.env.SMTP_SECURE === 'true' || port === 465;
+  const user = process.env.SMTP_USER;
+  const pass = process.env.SMTP_PASS;
+
+  const config = { host, port, secure };
+  if (user && pass) {
+    config.auth = { user, pass };
+  }
+  return config;
+}
+
+/**
+ * Factory to resolve or create appropriate email transport
+ * @param {Object} [options={}]
+ * @returns {Object} Transport instance with sendMail()
+ */
+function resolveTransport(options = {}) {
+  // 1. Direct custom transport provided
+  if (options.transport) {
+    return options.transport;
+  }
+
+  const backend = options.backend || options.type;
+
+  // 2. Explicit transport types
+  if (backend === 'memory' || options.memory === true) {
+    return new MemoryTransport(options);
+  }
+
+  if (backend === 'console' || options.console === true) {
+    return new ConsoleTransport(options);
+  }
+
+  if (backend === 'file' || options.fileDir) {
+    return new FileTransport({ dir: options.fileDir || options.dir });
+  }
+
+  // 3. SMTP configuration
+  const smtp = options.smtp || smtpFromEnv();
+  if (smtp && nodemailer) {
+    return nodemailer.createTransport(smtp);
+  }
+
+  // 4. Fallback defaults by environment
+  const env = process.env.NODE_ENV || 'development';
+  if (env === 'test') {
+    return new MemoryTransport(options);
+  }
+
+  if (!smtp) {
+    // If running in development with no SMTP, gracefully use MemoryTransport
+    return new MemoryTransport(options);
+  }
+
+  if (!nodemailer) {
+    throw new Error('nodemailer is required for SMTP transport. Install it with: npm install nodemailer');
+  }
+
+  return nodemailer.createTransport(smtp);
+}
+
+module.exports = {
+  MemoryTransport,
+  ConsoleTransport,
+  FileTransport,
+  resolveTransport,
+  smtpFromEnv,
+};