@mailzeno/core 0.1.0

package/README.md

@@ -0,0 +1,68 @@
+# @mailzeno/core
+
+SMTP engine powering MailZeno.
+
+Low-level email sending library with:
+
+- SMTP pooling
+- Retry logic
+- Exponential backoff
+- Transient error detection
+- React email rendering
+- Timeout handling
+
+---
+
+## Installation
+
+```bash
+npm install @mailzeno/core
+```
+
+---
+
+## Usage
+
+```ts
+import { sendEmail } from "@mailzeno/core"
+
+await sendEmail(
+  {
+    id: "smtp_id",
+    host: "smtp.example.com",
+    port: 587,
+    secure: false,
+    user: "username",
+    pass: "password"
+  },
+  {
+    from: "you@example.com",
+    to: "recipient@example.com",
+    subject: "Hello",
+    html: "<h1>Hello world</h1>"
+  }
+)
+```
+
+---
+
+## Features
+
+- SMTP connection pooling
+- AES-safe config handling (handled by parent app)
+- Automatic retries for transient failures
+- React email rendering support
+- Structured error mapping
+- ESM + CommonJS support
+
+---
+
+## Requirements
+
+- Node.js >= 18
+
+---
+
+## License
+
+MIT © MailZeno

package/dist/index.cjs

@@ -0,0 +1,254 @@
+"use strict";
+var __create = Object.create;
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getProtoOf = Object.getPrototypeOf;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(
+  // If the importer is in node compatibility mode or this is not an ESM
+  // file that has been converted to a CommonJS file using a Babel-
+  // compatible transform (i.e. "__esModule" has not been set), then set
+  // "default" to the CommonJS "module.exports" for node compatibility.
+  isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target,
+  mod
+));
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var index_exports = {};
+__export(index_exports, {
+  sendEmail: () => sendEmail
+});
+module.exports = __toCommonJS(index_exports);
+
+// src/smtp/transporter.ts
+var import_nodemailer = __toESM(require("nodemailer"), 1);
+var transporterCache = /* @__PURE__ */ new Map();
+function getCacheKey(smtp) {
+  return `${smtp.id}:${smtp.host}:${smtp.port}:${smtp.user}`;
+}
+function getTransporter(smtp) {
+  const key = getCacheKey(smtp);
+  if (transporterCache.has(key)) {
+    return transporterCache.get(key);
+  }
+  const transporter = import_nodemailer.default.createTransport({
+    host: smtp.host,
+    port: smtp.port,
+    secure: smtp.secure,
+    pool: true,
+    maxConnections: smtp.maxConnections ?? 5,
+    maxMessages: smtp.maxMessages ?? 1e3,
+    connectionTimeout: smtp.connectionTimeout ?? 1e4,
+    greetingTimeout: smtp.greetingTimeout ?? 1e4,
+    socketTimeout: smtp.socketTimeout ?? 15e3,
+    auth: {
+      user: smtp.user,
+      pass: smtp.pass
+    },
+    tls: {
+      rejectUnauthorized: true
+    }
+  });
+  transporter.on("error", () => {
+    transporterCache.delete(key);
+  });
+  transporterCache.set(key, transporter);
+  return transporter;
+}
+
+// src/retry/retry-queue.ts
+function isTransientError(error) {
+  const responseCode = error?.responseCode;
+  if (responseCode && responseCode >= 400 && responseCode < 500) {
+    return true;
+  }
+  if (error?.code === "ETIMEDOUT" || error?.code === "ECONNECTION") {
+    return true;
+  }
+  return false;
+}
+async function retry(fn, attempts = 3) {
+  let lastError;
+  for (let i = 0; i < attempts; i++) {
+    try {
+      return await fn();
+    } catch (err) {
+      lastError = err;
+      if (!isTransientError(err) || i === attempts - 1) {
+        throw err;
+      }
+      const delay = Math.pow(2, i) * 1e3 + Math.random() * 300;
+      await new Promise((res) => setTimeout(res, delay));
+    }
+  }
+  throw lastError;
+}
+
+// src/render/render-html.ts
+function renderHtml(html, text) {
+  const hasHtml = html && html.trim().length > 0;
+  const hasText = text && text.trim().length > 0;
+  if (!hasHtml && !hasText) {
+    throw new Error("Email must contain html or text");
+  }
+  return {
+    html: hasHtml ? html : void 0,
+    text: hasText ? text : void 0
+  };
+}
+
+// src/render/render-react.ts
+var import_render = require("@react-email/render");
+
+// src/errors.ts
+var MailZenoError = class extends Error {
+  constructor(message, code = "UNKNOWN_ERROR", options) {
+    super(message);
+    this.name = this.constructor.name;
+    this.code = code;
+    this.statusCode = options?.statusCode;
+    this.cause = options?.cause;
+    Object.setPrototypeOf(this, new.target.prototype);
+    if (Error.captureStackTrace) {
+      Error.captureStackTrace(this, this.constructor);
+    }
+  }
+};
+var ValidationError = class extends MailZenoError {
+  constructor(message, cause) {
+    super(message, "VALIDATION_ERROR", { statusCode: 400, cause });
+  }
+};
+var RenderError = class extends MailZenoError {
+  constructor(message, cause) {
+    super(message, "RENDER_ERROR", { cause });
+  }
+};
+var SMTPConnectionError = class extends MailZenoError {
+  constructor(message, cause) {
+    super(message, "SMTP_CONNECTION_ERROR", { cause });
+  }
+};
+var SMTPAuthError = class extends MailZenoError {
+  constructor(message, cause) {
+    super(message, "SMTP_AUTH_ERROR", { statusCode: 401, cause });
+  }
+};
+var SMTPResponseError = class extends MailZenoError {
+  constructor(message, cause) {
+    super(message, "SMTP_RESPONSE_ERROR", { cause });
+  }
+};
+var SMTPTimeoutError = class extends MailZenoError {
+  constructor(message, cause) {
+    super(message, "SMTP_TIMEOUT_ERROR", { cause });
+  }
+};
+
+// src/render/render-react.ts
+async function renderReact(component) {
+  try {
+    const html = await (0, import_render.render)(component);
+    return { html };
+  } catch (err) {
+    throw new RenderError("React email rendering failed", err);
+  }
+}
+
+// src/smtp/send.ts
+async function sendEmail(smtp, options) {
+  try {
+    if (!options.from || !options.to || !options.subject) {
+      throw new ValidationError(
+        "Missing required fields: from, to, subject"
+      );
+    }
+    let html = options.html;
+    let text = options.text;
+    if (options.react) {
+      try {
+        const rendered2 = await renderReact(options.react);
+        html = rendered2.html;
+      } catch (err) {
+        throw new RenderError("React email rendering failed", err);
+      }
+    }
+    const rendered = renderHtml(html, text);
+    const transporter = getTransporter(smtp);
+    const info = await retry(
+      () => transporter.sendMail({
+        from: options.from,
+        to: options.to,
+        subject: options.subject,
+        html: rendered.html,
+        text: rendered.text
+      })
+    );
+    return {
+      success: true,
+      messageId: info.messageId,
+      accepted: info.accepted,
+      rejected: info.rejected,
+      response: info.response
+    };
+  } catch (err) {
+    if (err instanceof MailZenoError) {
+      return {
+        success: false,
+        error: err.message
+      };
+    }
+    if (err?.code === "EAUTH") {
+      return {
+        success: false,
+        error: new SMTPAuthError(
+          "SMTP authentication failed",
+          err
+        ).message
+      };
+    }
+    if (err?.code === "ETIMEDOUT") {
+      return {
+        success: false,
+        error: new SMTPTimeoutError(
+          "SMTP connection timed out",
+          err
+        ).message
+      };
+    }
+    if (err?.code === "ECONNECTION") {
+      return {
+        success: false,
+        error: new SMTPConnectionError(
+          "SMTP connection failed",
+          err
+        ).message
+      };
+    }
+    return {
+      success: false,
+      error: new SMTPResponseError(
+        err?.message || "SMTP sending failed",
+        err
+      ).message
+    };
+  }
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  sendEmail
+});

package/dist/index.d.cts

@@ -0,0 +1,33 @@
+interface SMTPConfig {
+    id: string;
+    host: string;
+    port: number;
+    secure: boolean;
+    user: string;
+    pass: string;
+    connectionTimeout?: number;
+    greetingTimeout?: number;
+    socketTimeout?: number;
+    maxConnections?: number;
+    maxMessages?: number;
+}
+interface SendEmailOptions {
+    from: string;
+    to: string | string[];
+    subject: string;
+    html?: string;
+    text?: string;
+    react?: React.ReactElement;
+}
+interface SendEmailResponse {
+    success: boolean;
+    messageId?: string;
+    accepted?: string[];
+    rejected?: string[];
+    response?: string;
+    error?: string;
+}
+
+declare function sendEmail(smtp: SMTPConfig, options: SendEmailOptions): Promise<SendEmailResponse>;
+
+export { type SMTPConfig, type SendEmailOptions, type SendEmailResponse, sendEmail };

package/dist/index.d.ts

@@ -0,0 +1,33 @@
+interface SMTPConfig {
+    id: string;
+    host: string;
+    port: number;
+    secure: boolean;
+    user: string;
+    pass: string;
+    connectionTimeout?: number;
+    greetingTimeout?: number;
+    socketTimeout?: number;
+    maxConnections?: number;
+    maxMessages?: number;
+}
+interface SendEmailOptions {
+    from: string;
+    to: string | string[];
+    subject: string;
+    html?: string;
+    text?: string;
+    react?: React.ReactElement;
+}
+interface SendEmailResponse {
+    success: boolean;
+    messageId?: string;
+    accepted?: string[];
+    rejected?: string[];
+    response?: string;
+    error?: string;
+}
+
+declare function sendEmail(smtp: SMTPConfig, options: SendEmailOptions): Promise<SendEmailResponse>;
+
+export { type SMTPConfig, type SendEmailOptions, type SendEmailResponse, sendEmail };

package/dist/index.js

@@ -0,0 +1,217 @@
+// src/smtp/transporter.ts
+import nodemailer from "nodemailer";
+var transporterCache = /* @__PURE__ */ new Map();
+function getCacheKey(smtp) {
+  return `${smtp.id}:${smtp.host}:${smtp.port}:${smtp.user}`;
+}
+function getTransporter(smtp) {
+  const key = getCacheKey(smtp);
+  if (transporterCache.has(key)) {
+    return transporterCache.get(key);
+  }
+  const transporter = nodemailer.createTransport({
+    host: smtp.host,
+    port: smtp.port,
+    secure: smtp.secure,
+    pool: true,
+    maxConnections: smtp.maxConnections ?? 5,
+    maxMessages: smtp.maxMessages ?? 1e3,
+    connectionTimeout: smtp.connectionTimeout ?? 1e4,
+    greetingTimeout: smtp.greetingTimeout ?? 1e4,
+    socketTimeout: smtp.socketTimeout ?? 15e3,
+    auth: {
+      user: smtp.user,
+      pass: smtp.pass
+    },
+    tls: {
+      rejectUnauthorized: true
+    }
+  });
+  transporter.on("error", () => {
+    transporterCache.delete(key);
+  });
+  transporterCache.set(key, transporter);
+  return transporter;
+}
+
+// src/retry/retry-queue.ts
+function isTransientError(error) {
+  const responseCode = error?.responseCode;
+  if (responseCode && responseCode >= 400 && responseCode < 500) {
+    return true;
+  }
+  if (error?.code === "ETIMEDOUT" || error?.code === "ECONNECTION") {
+    return true;
+  }
+  return false;
+}
+async function retry(fn, attempts = 3) {
+  let lastError;
+  for (let i = 0; i < attempts; i++) {
+    try {
+      return await fn();
+    } catch (err) {
+      lastError = err;
+      if (!isTransientError(err) || i === attempts - 1) {
+        throw err;
+      }
+      const delay = Math.pow(2, i) * 1e3 + Math.random() * 300;
+      await new Promise((res) => setTimeout(res, delay));
+    }
+  }
+  throw lastError;
+}
+
+// src/render/render-html.ts
+function renderHtml(html, text) {
+  const hasHtml = html && html.trim().length > 0;
+  const hasText = text && text.trim().length > 0;
+  if (!hasHtml && !hasText) {
+    throw new Error("Email must contain html or text");
+  }
+  return {
+    html: hasHtml ? html : void 0,
+    text: hasText ? text : void 0
+  };
+}
+
+// src/render/render-react.ts
+import { render } from "@react-email/render";
+
+// src/errors.ts
+var MailZenoError = class extends Error {
+  constructor(message, code = "UNKNOWN_ERROR", options) {
+    super(message);
+    this.name = this.constructor.name;
+    this.code = code;
+    this.statusCode = options?.statusCode;
+    this.cause = options?.cause;
+    Object.setPrototypeOf(this, new.target.prototype);
+    if (Error.captureStackTrace) {
+      Error.captureStackTrace(this, this.constructor);
+    }
+  }
+};
+var ValidationError = class extends MailZenoError {
+  constructor(message, cause) {
+    super(message, "VALIDATION_ERROR", { statusCode: 400, cause });
+  }
+};
+var RenderError = class extends MailZenoError {
+  constructor(message, cause) {
+    super(message, "RENDER_ERROR", { cause });
+  }
+};
+var SMTPConnectionError = class extends MailZenoError {
+  constructor(message, cause) {
+    super(message, "SMTP_CONNECTION_ERROR", { cause });
+  }
+};
+var SMTPAuthError = class extends MailZenoError {
+  constructor(message, cause) {
+    super(message, "SMTP_AUTH_ERROR", { statusCode: 401, cause });
+  }
+};
+var SMTPResponseError = class extends MailZenoError {
+  constructor(message, cause) {
+    super(message, "SMTP_RESPONSE_ERROR", { cause });
+  }
+};
+var SMTPTimeoutError = class extends MailZenoError {
+  constructor(message, cause) {
+    super(message, "SMTP_TIMEOUT_ERROR", { cause });
+  }
+};
+
+// src/render/render-react.ts
+async function renderReact(component) {
+  try {
+    const html = await render(component);
+    return { html };
+  } catch (err) {
+    throw new RenderError("React email rendering failed", err);
+  }
+}
+
+// src/smtp/send.ts
+async function sendEmail(smtp, options) {
+  try {
+    if (!options.from || !options.to || !options.subject) {
+      throw new ValidationError(
+        "Missing required fields: from, to, subject"
+      );
+    }
+    let html = options.html;
+    let text = options.text;
+    if (options.react) {
+      try {
+        const rendered2 = await renderReact(options.react);
+        html = rendered2.html;
+      } catch (err) {
+        throw new RenderError("React email rendering failed", err);
+      }
+    }
+    const rendered = renderHtml(html, text);
+    const transporter = getTransporter(smtp);
+    const info = await retry(
+      () => transporter.sendMail({
+        from: options.from,
+        to: options.to,
+        subject: options.subject,
+        html: rendered.html,
+        text: rendered.text
+      })
+    );
+    return {
+      success: true,
+      messageId: info.messageId,
+      accepted: info.accepted,
+      rejected: info.rejected,
+      response: info.response
+    };
+  } catch (err) {
+    if (err instanceof MailZenoError) {
+      return {
+        success: false,
+        error: err.message
+      };
+    }
+    if (err?.code === "EAUTH") {
+      return {
+        success: false,
+        error: new SMTPAuthError(
+          "SMTP authentication failed",
+          err
+        ).message
+      };
+    }
+    if (err?.code === "ETIMEDOUT") {
+      return {
+        success: false,
+        error: new SMTPTimeoutError(
+          "SMTP connection timed out",
+          err
+        ).message
+      };
+    }
+    if (err?.code === "ECONNECTION") {
+      return {
+        success: false,
+        error: new SMTPConnectionError(
+          "SMTP connection failed",
+          err
+        ).message
+      };
+    }
+    return {
+      success: false,
+      error: new SMTPResponseError(
+        err?.message || "SMTP sending failed",
+        err
+      ).message
+    };
+  }
+}
+export {
+  sendEmail
+};

package/package.json

@@ -0,0 +1,53 @@
+{
+  "name": "@mailzeno/core",
+  "version": "0.1.0",
+  "description": "SMTP engine for MailZeno",
+  "license": "MIT",
+  "type": "module",
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "require": "./dist/index.cjs",
+      "types": "./dist/index.d.ts"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsup src/index.ts --format esm,cjs --dts --clean"
+  },
+  "keywords": [
+    "smtp",
+    "email",
+    "mailzeno",
+    "email-engine",
+    "transactional-email"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/mailzeno/mailzeno.git"
+  },
+  "bugs": {
+    "url": "https://github.com/mailzeno/mailzeno/issues"
+  },
+  "homepage": "https://github.com/mailzeno/mailzeno#readme",
+  "publishConfig": {
+    "access": "public"
+  },
+  "sideEffects": false,
+  "engines": {
+    "node": ">=18"
+  },
+  "dependencies": {
+    "@react-email/render": "^2.0.4",
+    "nodemailer": "^6.9.0"
+  },
+  "devDependencies": {
+    "tsup": "^8.0.0",
+    "typescript": "^5.0.0"
+  }
+}