@blamejs/core 0.4.21 → 0.4.22

package/CHANGELOG.md

@@ -8,6 +8,7 @@ upgrading across more than a few patches at a time.
 
 ## v0.4.x
 
+- **0.4.21** (2026-04-30) — b.queue: repeat-in-queue (cron) + parent-child Flows
 - **0.4.20** (2026-04-30) — b.queue + b.jobs: priority, rate-limit, progress
 - **0.4.19** (2026-04-30) — b.router: schema-validated routes + OpenAPI gen
 - **0.4.18** (2026-04-30) — cookieJar forensic-test strengthening (real crypto, replay, nonce)

package/lib/mail.js

@@ -38,9 +38,24 @@
  *       text:     "plain body"                (at least one of text/html)
  *       html:     "<p>...</p>"
  *       headers:  { "X-Custom": "v" }         (merged with defaults)
+ *       attachments: [{
+ *         filename:           "report.pdf",        // required
+ *         content:             buf,                // Buffer or string
+ *         contentType:         "application/pdf",  // default application/octet-stream
+ *         contentDisposition:  "attachment",       // or "inline"
+ *         cid:                 "logo-1",            // for inline images:
+ *                                                  // <img src="cid:logo-1">
+ *       }, ...]
  *     }
  *     → whatever the transport returned
  *
+ * When attachments are present the SMTP transport wraps the body in
+ * multipart/mixed; text+html bodies still use multipart/alternative
+ * inside. Resend's http preset forwards attachments via the Resend API
+ * shape (base64 content + content_id for inline). Operators wiring
+ * other vendors against httpTransport include attachments in their
+ * own serialize() per-vendor.
+ *
  * Validation surface uses MailError (FrameworkError subclass) with
  * permanent flag. Distinct codes per failure: missing-to, missing-from,
  * missing-body, invalid-recipient, transport-failed, smtp-*, http-*,
@@ -128,6 +143,52 @@ function _validateMessage(message) {
     throw new MailError("mail/missing-body",
       "message must include at least one of text or html", true);
   }
+
+  if (message.attachments !== undefined) {
+    if (!Array.isArray(message.attachments)) {
+      throw new MailError("mail/invalid-attachments",
+        "message.attachments must be an array", true);
+    }
+    for (var i = 0; i < message.attachments.length; i++) {
+      var att = message.attachments[i];
+      if (!att || typeof att !== "object") {
+        throw new MailError("mail/invalid-attachment",
+          "attachments[" + i + "] must be an object", true);
+      }
+      if (typeof att.filename !== "string" || att.filename.length === 0) {
+        throw new MailError("mail/invalid-attachment",
+          "attachments[" + i + "].filename must be a non-empty string", true);
+      }
+      if (/[\r\n\0]/.test(att.filename)) {
+        throw new MailError("mail/invalid-attachment",
+          "attachments[" + i + "].filename contains forbidden control characters", true);
+      }
+      if (att.content === undefined || att.content === null) {
+        throw new MailError("mail/invalid-attachment",
+          "attachments[" + i + "].content is required (Buffer or string)", true);
+      }
+      if (!Buffer.isBuffer(att.content) && typeof att.content !== "string") {
+        throw new MailError("mail/invalid-attachment",
+          "attachments[" + i + "].content must be a Buffer or string", true);
+      }
+      if (att.contentType !== undefined &&
+          (typeof att.contentType !== "string" || /[\r\n\0]/.test(att.contentType))) {
+        throw new MailError("mail/invalid-attachment",
+          "attachments[" + i + "].contentType must be a clean string", true);
+      }
+      if (att.contentDisposition !== undefined &&
+          att.contentDisposition !== "attachment" &&
+          att.contentDisposition !== "inline") {
+        throw new MailError("mail/invalid-attachment",
+          "attachments[" + i + "].contentDisposition must be 'attachment' or 'inline'", true);
+      }
+      if (att.cid !== undefined &&
+          (typeof att.cid !== "string" || /[\r\n\0<>]/.test(att.cid))) {
+        throw new MailError("mail/invalid-attachment",
+          "attachments[" + i + "].cid must be a clean string (no <>)", true);
+      }
+    }
+  }
 }
 
 function _mergeMessage(defaults, message) {
@@ -201,6 +262,59 @@ function memoryTransport() {
 // cleartext port the transport always issues STARTTLS and refuses
 // to send AUTH or DATA in cleartext if the upgrade is rejected.
 
+function _newBoundary(label) {
+  return "blamejs-" + label + "-" + Date.now() + "-" + Math.floor(Math.random() * 1e9);
+}
+
+// base64-encode the buffer with line wrapping at 76 chars (RFC 2045
+// §6.8). Most clients tolerate longer lines but the spec maximum is
+// 998 octets per line; sticking to 76 keeps everyone happy.
+function _base64Wrap(buf) {
+  var b64 = buf.toString("base64");
+  var lines = [];
+  for (var i = 0; i < b64.length; i += 76) lines.push(b64.slice(i, i + 76));
+  return lines.join("\r\n");
+}
+
+function _buildAttachmentPart(att) {
+  var content = Buffer.isBuffer(att.content) ? att.content : Buffer.from(String(att.content), "utf8");
+  var contentType = att.contentType || "application/octet-stream";
+  var disposition = att.contentDisposition || (att.cid ? "inline" : "attachment");
+  var lines = [];
+  lines.push("Content-Type: " + contentType + '; name="' + att.filename + '"');
+  lines.push("Content-Transfer-Encoding: base64");
+  lines.push("Content-Disposition: " + disposition + '; filename="' + att.filename + '"');
+  if (att.cid) lines.push("Content-ID: <" + att.cid + ">");
+  lines.push("");
+  lines.push(_base64Wrap(content));
+  return lines.join("\r\n");
+}
+
+function _buildBodyPart(message) {
+  // Text + html → multipart/alternative; otherwise single-part.
+  if (message.text && message.html) {
+    var altBoundary = _newBoundary("alt");
+    return {
+      contentType: 'multipart/alternative; boundary="' + altBoundary + '"',
+      body: [
+        "--" + altBoundary,
+        "Content-Type: text/plain; charset=utf-8",
+        "",
+        message.text,
+        "--" + altBoundary,
+        "Content-Type: text/html; charset=utf-8",
+        "",
+        message.html,
+        "--" + altBoundary + "--",
+      ].join("\r\n"),
+    };
+  }
+  if (message.html) {
+    return { contentType: "text/html; charset=utf-8", body: message.html };
+  }
+  return { contentType: "text/plain; charset=utf-8", body: message.text || "" };
+}
+
 function _buildRfc822(message) {
   var headers = [];
   headers.push("From: " + message.from);
@@ -221,27 +335,32 @@ function _buildRfc822(message) {
     }
   }
 
+  var attachments = Array.isArray(message.attachments) ? message.attachments : [];
+  var inner = _buildBodyPart(message);
   var body;
-  if (message.text && message.html) {
-    var boundary = "blamejs-mail-" + Date.now() + "-" + Math.floor(Math.random() * 1e9);
-    headers.push('Content-Type: multipart/alternative; boundary="' + boundary + '"');
-    body = [
-      "--" + boundary,
-      "Content-Type: text/plain; charset=utf-8",
-      "",
-      message.text,
-      "--" + boundary,
-      "Content-Type: text/html; charset=utf-8",
-      "",
-      message.html,
-      "--" + boundary + "--",
-    ].join("\r\n");
-  } else if (message.html) {
-    headers.push("Content-Type: text/html; charset=utf-8");
-    body = message.html;
+
+  if (attachments.length === 0) {
+    headers.push("Content-Type: " + inner.contentType);
+    body = inner.body;
   } else {
-    headers.push("Content-Type: text/plain; charset=utf-8");
-    body = message.text || "";
+    // multipart/mixed: first part is the body (single or alternative),
+    // subsequent parts are the attachments. Inline disposition + Content-ID
+    // is interpreted correctly by every major client even inside mixed;
+    // operators with strict-RFC-2387 multipart/related needs subscribe
+    // to a future patch when demand surfaces.
+    var mixedBoundary = _newBoundary("mixed");
+    headers.push('Content-Type: multipart/mixed; boundary="' + mixedBoundary + '"');
+    var parts = [];
+    parts.push("--" + mixedBoundary);
+    parts.push("Content-Type: " + inner.contentType);
+    parts.push("");
+    parts.push(inner.body);
+    for (var ai = 0; ai < attachments.length; ai++) {
+      parts.push("--" + mixedBoundary);
+      parts.push(_buildAttachmentPart(attachments[ai]));
+    }
+    parts.push("--" + mixedBoundary + "--");
+    body = parts.join("\r\n");
   }
 
   // Normalize line endings then dot-stuff per SMTP transparency.
@@ -587,6 +706,21 @@ function resendTransport(opts) {
       if (message.html)    payload.html     = message.html;
       if (message.text)    payload.text     = message.text;
       if (message.headers) payload.headers  = message.headers;
+      // Resend attachments shape: [{ filename, content (base64 string),
+      // contentType?, content_id? }]. Inline images via cid go through
+      // the content_id field (Resend renders <img src="cid:...">).
+      if (Array.isArray(message.attachments) && message.attachments.length > 0) {
+        payload.attachments = message.attachments.map(function (att) {
+          var buf = Buffer.isBuffer(att.content) ? att.content : Buffer.from(String(att.content), "utf8");
+          var entry = {
+            filename: att.filename,
+            content:  buf.toString("base64"),
+          };
+          if (att.contentType) entry.contentType = att.contentType;
+          if (att.cid)         entry.content_id  = att.cid;
+          return entry;
+        });
+      }
       return { body: JSON.stringify(payload) };
     },
     interpret: function (res) {
@@ -694,6 +828,9 @@ function create(opts) {
 module.exports = {
   create:     create,
   MailError:  MailError,
+  // Test-only export: lets unit tests inspect the wire format without
+  // standing up a TLS-capable SMTP fixture. Operators don't call this.
+  _buildRfc822ForTest: _buildRfc822,
   transports: {
     console: consoleTransport,
     memory:  memoryTransport,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@blamejs/core",
-  "version": "0.4.21",
+  "version": "0.4.22",
   "description": "The Node framework that owns its stack.",
   "license": "Apache-2.0",
   "author": "blamejs contributors",