webspresso 0.0.80 → 0.0.81

package/plugins/email/manifest.js

@@ -0,0 +1,25 @@
+/**
+ * Build manifest helpers for email plugin
+ * @module plugins/email/manifest
+ */
+
+/**
+ * @param {object} manifest
+ * @returns {{ templates: Record<string, { mjml?: string, html?: string }>, emailTemplates: Record<string, object> }}
+ */
+function emailPluginOptionsFromManifest(manifest) {
+  const chunks = manifest?.emailTemplates || {};
+  /** @type {Record<string, { mjml?: string, html?: string }>} */
+  const templates = {};
+
+  for (const [id, chunk] of Object.entries(chunks)) {
+    if (chunk?.mjml) templates[id] = { mjml: chunk.mjml };
+    else if (chunk?.html) templates[id] = { html: chunk.html };
+  }
+
+  return { templates, emailTemplates: chunks };
+}
+
+module.exports = {
+  emailPluginOptionsFromManifest,
+};

package/plugins/email/migration-template.js

@@ -0,0 +1,40 @@
+/**
+ * Migration template for email_logs table
+ * @module plugins/email/migration-template
+ */
+
+/**
+ * @param {string} [tableName='email_logs']
+ * @returns {string}
+ */
+function generateEmailLogsMigration(tableName = 'email_logs') {
+  return `/**
+ * Migration: Create ${tableName} table
+ * Auto-generated by email plugin
+ */
+
+exports.up = function(knex) {
+  return knex.schema.createTable('${tableName}', (table) => {
+    table.bigIncrements('id').primary();
+    table.string('to', 1000).nullable();
+    table.string('cc', 1000).nullable();
+    table.string('bcc', 1000).nullable();
+    table.string('subject', 500).nullable();
+    table.string('template_id', 255).nullable().index();
+    table.string('from', 255).nullable();
+    table.string('status', 16).notNullable().index();
+    table.string('message_id', 255).nullable();
+    table.text('error').nullable();
+    table.timestamp('created_at').defaultTo(knex.fn.now()).notNullable().index();
+  });
+};
+
+exports.down = function(knex) {
+  return knex.schema.dropTableIfExists('${tableName}');
+};
+`;
+}
+
+module.exports = {
+  generateEmailLogsMigration,
+};

package/plugins/email/purge.js

@@ -0,0 +1,28 @@
+/**
+ * Delete email log rows older than a cutoff
+ * @module plugins/email/purge
+ */
+
+/**
+ * @param {import('knex').Knex} knex
+ * @param {Object} options
+ * @param {string} [options.tableName='email_logs']
+ * @param {Date|string} options.olderThan
+ * @returns {Promise<number>}
+ */
+async function purgeEmailLogs(knex, options) {
+  const tableName = options.tableName || 'email_logs';
+  const olderThan = options.olderThan instanceof Date
+    ? options.olderThan
+    : new Date(options.olderThan);
+
+  if (Number.isNaN(olderThan.getTime())) {
+    throw new Error('purgeEmailLogs: invalid olderThan date');
+  }
+
+  return knex(tableName).where('created_at', '<', olderThan).delete();
+}
+
+module.exports = {
+  purgeEmailLogs,
+};

package/plugins/email/render.js

@@ -0,0 +1,154 @@
+/**
+ * MJML / HTML rendering with {{var}} interpolation
+ * @module plugins/email/render
+ */
+
+const fsEnv = require('./fs-env');
+
+let mjml2html;
+try {
+  mjml2html = require('mjml');
+} catch {
+  mjml2html = null;
+}
+
+/**
+ * Resolve dot-path on data object
+ * @param {Object} data
+ * @param {string} keyPath
+ * @returns {*}
+ */
+function getNestedValue(data, keyPath) {
+  if (!data || !keyPath) return '';
+  const parts = keyPath.split('.');
+  let cur = data;
+  for (const p of parts) {
+    if (cur == null || typeof cur !== 'object') return '';
+    cur = cur[p];
+  }
+  if (cur == null) return '';
+  return String(cur);
+}
+
+/**
+ * Replace {{key}} and {{a.b}} placeholders
+ * @param {string} source
+ * @param {Object} [data={}]
+ * @returns {string}
+ */
+function interpolate(source, data = {}) {
+  if (!source) return '';
+  return String(source).replace(/\{\{\s*([\w.]+)\s*\}\}/g, (_, key) => getNestedValue(data, key));
+}
+
+/**
+ * Read file if path exists (Node.js only)
+ * @param {string} filePath
+ * @returns {string|null}
+ */
+function readFileIfExists(filePath) {
+  return fsEnv.readFileUtf8(filePath);
+}
+
+/**
+ * Normalize template source to { mjml?, html?, text? }
+ * @param {string|Object} source
+ * @returns {{ mjml?: string, html?: string, text?: string }}
+ */
+function normalizeSource(source) {
+  if (typeof source === 'string') {
+    if (fsEnv.isInlineMarkup(source)) {
+      const trimmed = source.trim();
+      if (trimmed.startsWith('<mjml')) {
+        return { mjml: source };
+      }
+      return { html: source };
+    }
+
+    if (fsEnv.looksLikeFilePath(source)) {
+      const content = fsEnv.readFileUtf8(source);
+      if (content == null) {
+        if (!fsEnv.isFilesystemAvailable()) {
+          throw new Error(
+            `Template path "${source}" requires Node.js filesystem (unavailable on edge runtimes). ` +
+            'Use inline { mjml: "..." }, registerTemplate(id, { mjml }), or pass MJML/HTML strings directly.'
+          );
+        }
+        throw new Error(`Template file not found: ${source}`);
+      }
+      if (source.endsWith('.mjml')) {
+        return { mjml: content };
+      }
+      return { html: content };
+    }
+
+    return { html: source };
+  }
+
+  if (source && typeof source === 'object') {
+    if (source.path) {
+      return normalizeSource(source.path);
+    }
+    if (source.mjml) {
+      return { mjml: source.mjml };
+    }
+    if (source.html) {
+      return { html: source.html };
+    }
+    if (source.text) {
+      return { text: source.text };
+    }
+  }
+
+  throw new Error('Invalid template source');
+}
+
+/**
+ * Compile MJML to HTML
+ * @param {string} mjmlSource
+ * @returns {Promise<{ html: string, errors: Array }>}
+ */
+async function compileMjml(mjmlSource) {
+  if (!mjml2html) {
+    throw new Error('mjml is required for MJML templates. Install it with: npm install mjml');
+  }
+  const result = await mjml2html(mjmlSource, { validationLevel: 'soft' });
+  return {
+    html: result.html,
+    errors: result.errors || [],
+  };
+}
+
+/**
+ * Render template source with data
+ * @param {string|Object} source
+ * @param {Object} [data={}]
+ * @returns {Promise<{ html?: string, text?: string, errors?: Array }>}
+ */
+async function renderSource(source, data = {}) {
+  const normalized = normalizeSource(source);
+
+  if (normalized.mjml) {
+    const interpolated = interpolate(normalized.mjml, data);
+    const { html, errors } = await compileMjml(interpolated);
+    return { html, errors };
+  }
+
+  if (normalized.html) {
+    return { html: interpolate(normalized.html, data) };
+  }
+
+  if (normalized.text) {
+    return { text: interpolate(normalized.text, data) };
+  }
+
+  return {};
+}
+
+module.exports = {
+  interpolate,
+  normalizeSource,
+  compileMjml,
+  renderSource,
+  readFileIfExists,
+};

package/plugins/email/service.js

@@ -0,0 +1,244 @@
+/**
+ * Email service — send, preview, verify, logging
+ * @module plugins/email/service
+ */
+
+const { renderSource } = require('./render');
+const { createTransport, resolveDefaultFrom } = require('./transport');
+
+/**
+ * @param {Object} options
+ * @param {import('./template-registry').TemplateRegistry} options.registry
+ * @param {Object} [options.transportOptions]
+ * @param {Object} [options.defaults]
+ * @param {import('knex').Knex|null} [options.knex]
+ * @param {boolean} [options.logToDb=false]
+ * @param {string} [options.tableName='email_logs']
+ */
+function createEmailService(options) {
+  const registry = options.registry;
+  const defaults = options.defaults || {};
+  const knex = options.knex || null;
+  const logToDb = options.logToDb === true && !!knex;
+  const tableName = options.tableName || 'email_logs';
+
+  let transport;
+  try {
+    transport = createTransport(options.transportOptions || {});
+  } catch (err) {
+    transport = null;
+    console.warn('[email]', err.message);
+  }
+
+  /**
+   * @param {Object} row
+   */
+  async function writeLog(row) {
+    if (!logToDb) return;
+    try {
+      await knex(tableName).insert({
+        to: row.to || null,
+        cc: row.cc || null,
+        bcc: row.bcc || null,
+        subject: row.subject || null,
+        template_id: row.template_id || null,
+        from: row.from || null,
+        status: row.status,
+        message_id: row.message_id || null,
+        error: row.error || null,
+        created_at: new Date(),
+      });
+    } catch (err) {
+      console.warn('[email] Failed to write email log:', err.message);
+    }
+  }
+
+  /**
+   * @param {Object} sendOptions
+   * @returns {Promise<Object>}
+   */
+  async function send(sendOptions = {}) {
+    if (!transport) {
+      throw new Error('Email transport is not configured');
+    }
+
+    const {
+      to,
+      cc,
+      bcc,
+      subject,
+      from,
+      replyTo,
+      template,
+      mjml,
+      html,
+      text,
+      data = {},
+      attachments,
+    } = sendOptions;
+
+    if (!to) {
+      throw new Error('Email "to" is required');
+    }
+    if (!subject) {
+      throw new Error('Email "subject" is required');
+    }
+
+    let renderedHtml = html;
+    let renderedText = text;
+    let mjmlErrors = [];
+    let templateId = template || null;
+
+    if (template) {
+      const entry = registry.get(template);
+      if (!entry) {
+        throw new Error(`Unknown email template: ${template}`);
+      }
+      const rendered = await renderSource(entry.source, data);
+      renderedHtml = rendered.html || renderedHtml;
+      renderedText = rendered.text || renderedText;
+      mjmlErrors = rendered.errors || [];
+    } else if (mjml) {
+      const rendered = await renderSource({ mjml }, data);
+      renderedHtml = rendered.html;
+      mjmlErrors = rendered.errors || [];
+    } else if (html && data && Object.keys(data).length) {
+      const rendered = await renderSource({ html }, data);
+      renderedHtml = rendered.html;
+    }
+
+    const mailOptions = {
+      to,
+      cc,
+      bcc,
+      subject,
+      from: from || resolveDefaultFrom(defaults),
+      replyTo: replyTo || defaults.replyTo,
+      html: renderedHtml,
+      text: renderedText,
+      attachments,
+    };
+
+    try {
+      const info = await transport.sendMail(mailOptions);
+      await writeLog({
+        to: Array.isArray(to) ? to.join(',') : String(to),
+        cc: cc ? (Array.isArray(cc) ? cc.join(',') : String(cc)) : null,
+        bcc: bcc ? (Array.isArray(bcc) ? bcc.join(',') : String(bcc)) : null,
+        subject,
+        template_id: templateId,
+        from: mailOptions.from,
+        status: 'sent',
+        message_id: info.messageId || null,
+      });
+      return { ok: true, messageId: info.messageId, mjmlErrors };
+    } catch (err) {
+      await writeLog({
+        to: Array.isArray(to) ? to.join(',') : String(to),
+        cc: cc ? (Array.isArray(cc) ? cc.join(',') : String(cc)) : null,
+        bcc: bcc ? (Array.isArray(bcc) ? bcc.join(',') : String(bcc)) : null,
+        subject,
+        template_id: templateId,
+        from: mailOptions.from,
+        status: 'failed',
+        error: err.message,
+      });
+      throw err;
+    }
+  }
+
+  /**
+   * @param {string} name
+   * @param {Object} options
+   */
+  async function sendTemplate(name, options = {}) {
+    return send({ ...options, template: name });
+  }
+
+  /**
+   * @param {string|Object} nameOrOptions
+   * @param {Object} [data={}]
+   */
+  async function preview(nameOrOptions, data = {}) {
+    if (typeof nameOrOptions === 'string') {
+      const entry = registry.get(nameOrOptions);
+      if (!entry) {
+        throw new Error(`Unknown email template: ${nameOrOptions}`);
+      }
+      return renderSource(entry.source, data);
+    }
+
+    if (nameOrOptions.template) {
+      const entry = registry.get(nameOrOptions.template);
+      if (!entry) {
+        throw new Error(`Unknown email template: ${nameOrOptions.template}`);
+      }
+      return renderSource(entry.source, nameOrOptions.data || data);
+    }
+
+    if (nameOrOptions.mjml) {
+      return renderSource({ mjml: nameOrOptions.mjml }, nameOrOptions.data || data);
+    }
+
+    if (nameOrOptions.html) {
+      return renderSource({ html: nameOrOptions.html }, nameOrOptions.data || data);
+    }
+
+    throw new Error('preview requires template id, mjml, or html');
+  }
+
+  async function verifyConnection() {
+    if (!transport) {
+      throw new Error('Email transport is not configured');
+    }
+    return transport.verify();
+  }
+
+  /**
+   * @param {Object} [filters={}]
+   */
+  async function queryLogs(filters = {}) {
+    if (!knex) return [];
+
+    const page = Math.max(1, parseInt(filters.page, 10) || 1);
+    const perPage = Math.min(100, Math.max(1, parseInt(filters.perPage, 10) || 25));
+    const offset = filters.offset != null ? Math.max(0, filters.offset) : (page - 1) * perPage;
+    const limit = filters.limit != null ? Math.min(500, filters.limit) : perPage;
+
+    let qb = knex(tableName).orderBy('created_at', 'desc');
+
+    if (filters.status) qb = qb.where('status', String(filters.status));
+    if (filters.template) qb = qb.where('template_id', String(filters.template));
+    if (filters.from) qb = qb.where('created_at', '>=', String(filters.from));
+    if (filters.to) qb = qb.where('created_at', '<=', String(filters.to));
+
+    const rows = await qb.offset(offset).limit(limit);
+
+    if (filters.includeTotal) {
+      let countQ = knex(tableName);
+      if (filters.status) countQ = countQ.where('status', String(filters.status));
+      if (filters.template) countQ = countQ.where('template_id', String(filters.template));
+      if (filters.from) countQ = countQ.where('created_at', '>=', String(filters.from));
+      if (filters.to) countQ = countQ.where('created_at', '<=', String(filters.to));
+      const countRow = await countQ.count('* as cnt').first();
+      const total = Number(countRow?.cnt ?? Object.values(countRow || {})[0] ?? 0);
+      return { data: rows, meta: { page, perPage: limit, total, offset } };
+    }
+
+    return rows;
+  }
+
+  return {
+    send,
+    sendTemplate,
+    preview,
+    verifyConnection,
+    queryLogs,
+    getTransport: () => transport,
+    isTransportReady: () => !!transport,
+  };
+}
+
+module.exports = {
+  createEmailService,
+};

package/plugins/email/template-registry.js

@@ -0,0 +1,134 @@
+/**
+ * Email template registry — inline, config map, optional Node.js directory scan
+ * @module plugins/email/template-registry
+ */
+
+const path = require('path');
+const fsEnv = require('./fs-env');
+
+/**
+ * @typedef {Object} TemplateEntry
+ * @property {string} id
+ * @property {'inline'|'path'} kind
+ * @property {string|Object} source
+ */
+
+class TemplateRegistry {
+  constructor() {
+    /** @type {Map<string, TemplateEntry>} */
+    this._templates = new Map();
+  }
+
+  /**
+   * Load *.mjml files from directory (Node.js only; no-op on edge)
+   * @param {string} dir
+   * @returns {number} Number of templates registered
+   */
+  loadFromDir(dir) {
+    const files = fsEnv.listMjmlBasenamesInDir(dir);
+    if (files == null) {
+      console.warn(
+        '[email] templatesDir skipped — filesystem unavailable (edge/worker runtime). ' +
+        'Use templates: { id: { mjml: "..." } } or registerTemplate with inline sources.'
+      );
+      return 0;
+    }
+
+    const resolved = path.resolve(dir);
+    let count = 0;
+    for (const file of files) {
+      const id = path.basename(file, '.mjml');
+      const filePath = path.join(resolved, file);
+      const content = fsEnv.readFileUtf8(filePath);
+      if (content != null) {
+        this.register(id, { mjml: content }, 'inline');
+        count += 1;
+      }
+    }
+    return count;
+  }
+
+  /**
+   * Register templates from config map (paths are inlined when fs is available)
+   * @param {Record<string, string|Object>} templates
+   */
+  loadFromMap(templates = {}) {
+    for (const [id, source] of Object.entries(templates)) {
+      if (typeof source === 'string' && fsEnv.looksLikeFilePath(source) && !fsEnv.isInlineMarkup(source)) {
+        const content = fsEnv.readFileUtf8(source);
+        if (content != null) {
+          this.register(
+            id,
+            source.endsWith('.mjml') ? { mjml: content } : { html: content },
+            'inline'
+          );
+          continue;
+        }
+        this.register(id, source, 'path');
+        continue;
+      }
+
+      this.register(id, source, 'inline');
+    }
+  }
+
+  /**
+   * @param {string} id
+   * @param {string|Object} source
+   * @param {'inline'|'path'} [kind='inline']
+   */
+  register(id, source, kind = 'inline') {
+    if (!id) throw new Error('Template id is required');
+    this._templates.set(id, { id, kind, source });
+  }
+
+  /**
+   * @param {string} id
+   * @returns {TemplateEntry|null}
+   */
+  get(id) {
+    return this._templates.get(id) || null;
+  }
+
+  /**
+   * @returns {Array<{ id: string, kind: string }>}
+   */
+  list() {
+    return Array.from(this._templates.values()).map((t) => ({
+      id: t.id,
+      kind: t.kind,
+    }));
+  }
+
+  /**
+   * Load templates embedded in build manifest (edge/worker safe)
+   * @param {Record<string, { mjml?: string, html?: string }>} emailTemplates
+   * @returns {number}
+   */
+  loadFromManifest(emailTemplates = {}) {
+    let count = 0;
+    for (const [id, chunk] of Object.entries(emailTemplates)) {
+      if (!chunk) continue;
+      if (chunk.mjml) {
+        this.register(id, { mjml: chunk.mjml }, 'inline');
+        count += 1;
+      } else if (chunk.html) {
+        this.register(id, { html: chunk.html }, 'inline');
+        count += 1;
+      }
+    }
+    return count;
+  }
+
+  /**
+   * @param {string} id
+   * @returns {boolean}
+   */
+  has(id) {
+    return this._templates.has(id);
+  }
+}
+
+module.exports = {
+  TemplateRegistry,
+};

package/plugins/email/templates/auth-email-verify.mjml

@@ -0,0 +1,13 @@
+<mjml>
+  <mj-body background-color="#f4f4f5">
+    <mj-section background-color="#ffffff" padding="32px 24px">
+      <mj-column>
+        <mj-text font-size="20px" font-weight="600" color="#18181b">Verify your email</mj-text>
+        <mj-text color="#52525b">Hi {{name}},</mj-text>
+        <mj-text color="#52525b">Please confirm your email address by clicking the button below.</mj-text>
+        <mj-button background-color="#2563eb" href="{{verifyUrl}}">Verify email</mj-button>
+        <mj-text color="#71717a" font-size="12px">If you did not create an account, you can ignore this message.</mj-text>
+      </mj-column>
+    </mj-section>
+  </mj-body>
+</mjml>

package/plugins/email/templates/auth-password-reset.mjml

@@ -0,0 +1,13 @@
+<mjml>
+  <mj-body background-color="#f4f4f5">
+    <mj-section background-color="#ffffff" padding="32px 24px">
+      <mj-column>
+        <mj-text font-size="20px" font-weight="600" color="#18181b">Reset your password</mj-text>
+        <mj-text color="#52525b">Hi {{name}},</mj-text>
+        <mj-text color="#52525b">We received a request to reset your password. Click the button below to choose a new one.</mj-text>
+        <mj-button background-color="#2563eb" href="{{resetUrl}}">Reset password</mj-button>
+        <mj-text color="#71717a" font-size="12px">If you did not request this, you can safely ignore this email.</mj-text>
+      </mj-column>
+    </mj-section>
+  </mj-body>
+</mjml>

package/plugins/email/templates/auth-welcome.mjml

@@ -0,0 +1,11 @@
+<mjml>
+  <mj-body background-color="#f4f4f5">
+    <mj-section background-color="#ffffff" padding="32px 24px">
+      <mj-column>
+        <mj-text font-size="20px" font-weight="600" color="#18181b">Welcome</mj-text>
+        <mj-text color="#52525b">Hi {{name}},</mj-text>
+        <mj-text color="#52525b">Thanks for joining us. Your account is ready.</mj-text>
+      </mj-column>
+    </mj-section>
+  </mj-body>
+</mjml>