@emailens/engine 0.7.0 → 0.8.0

package/README.md

@@ -1,6 +1,6 @@
 # @emailens/engine
 
-Email compatibility engine that transforms CSS per email client, analyzes compatibility, scores results, simulates dark mode, provides framework-aware fix snippets, and runs spam, accessibility, link, image, inbox preview, size, and template variable analysis.
+Email compatibility engine that transforms CSS per email client, analyzes compatibility across **250+ CSS properties**, scores results, simulates dark mode, provides framework-aware fix snippets, checks DNS deliverability (SPF, DKIM, DMARC, MX, BIMI), and runs content hygiene, accessibility, link, image, inbox preview, size, and template variable analysis.
 
 Supports **12 email clients**: Gmail (Web, Android, iOS), Outlook (365, Windows), Apple Mail (macOS, iOS), Yahoo Mail, Samsung Mail, Thunderbird, HEY Mail, and Superhuman.
 
@@ -140,6 +140,7 @@ const darkMode = session.simulateDarkMode("gmail-web");
 | `extractInboxPreview()` | Yes | Subject line and preheader extraction |
 | `checkSize()` | Yes | Gmail clipping size check |
 | `checkTemplateVariables()` | Yes | Unresolved template variable detection |
+| `checkDeliverability(domain)` | — | DNS deliverability check (async, SPF/DKIM/DMARC/MX/BIMI) |
 | `transformForClient(clientId)` | No | Transform for one client |
 | `transformForAllClients()` | No | Transform for all 12 clients |
 | `simulateDarkMode(clientId)` | No | Dark mode simulation |
@@ -184,7 +185,9 @@ Get only warnings that require HTML restructuring (`fixType: "structural"`).
 
 ### `analyzeSpam(html: string, options?: SpamAnalysisOptions): SpamReport`
 
-Analyzes an HTML email for spam indicators. Returns a 0–100 score (100 = clean) and an array of issues. Uses heuristic rules modeled after SpamAssassin, CAN-SPAM, and GDPR.
+Analyzes an HTML email for content hygiene issues. Returns a 0–100 score (100 = clean) and an array of issues. Uses heuristic rules modeled after SpamAssassin, CAN-SPAM, and GDPR.
+
+> **Note:** Content hygiene heuristics — not a real spam filter. This checks for common anti-patterns that trigger spam filters but cannot predict actual inbox placement. For real spam testing, use the `checkSpamAssassin()` integration or a dedicated service.
 
 ```typescript
 import { analyzeSpam } from "@emailens/engine";
@@ -280,6 +283,49 @@ const report = checkTemplateVariables(html);
 
 ---
 
+### `checkDeliverability(domain, options?): Promise<DeliverabilityReport>`
+
+Validates email deliverability for a domain by checking MX, SPF, DKIM, DMARC, and BIMI DNS records. All DNS queries have a 5-second timeout. No external dependencies — uses `node:dns/promises`.
+
+```typescript
+import { checkDeliverability } from "@emailens/engine";
+
+const report = await checkDeliverability("example.com");
+console.log(report.score);   // 0-100
+console.log(report.checks);  // individual check results
+console.log(report.issues);  // actionable issues
+```
+
+**Checks:**
+- **MX** — domain can receive email
+- **SPF** — authorized senders (`v=spf1`), flags dangerous `+all`
+- **DKIM** — probes 15 common selectors (`google`, `selector1`, `default`, `dkim`, etc.)
+- **DMARC** — policy enforcement (`v=DMARC1`), warns on `p=none`
+- **BIMI** — brand indicator (optional, nice-to-have)
+
+Also available as a session method: `session.checkDeliverability("example.com")`.
+
+> **Note:** This is standalone async — not wired into the synchronous `auditEmail()` pipeline.
+
+### `checkSpamAssassin(input, options?): Promise<SpamAssassinResult | null>`
+
+Opt-in integration with a local SpamAssassin installation. Shells out to `spamc` (daemon) or `spamassassin` (standalone) via `execFile`. Returns `null` if SpamAssassin is not installed.
+
+```typescript
+import { checkSpamAssassin } from "@emailens/engine";
+
+const result = await checkSpamAssassin(rawRfc2822Message);
+if (result) {
+  console.log(result.score);      // e.g. 3.2
+  console.log(result.isSpam);     // true if score >= threshold
+  console.log(result.rules);      // matched SpamAssassin rules
+}
+```
+
+> **Note:** Requires a full RFC 2822 message (headers + body), not just HTML.
+
+---
+
 ### `transformForClient(html, clientId, framework?): TransformResult`
 
 Transforms HTML for a specific email client — strips unsupported CSS, inlines `<style>` blocks (for Gmail), removes unsupported elements.
@@ -597,6 +643,29 @@ interface ImageReport {
   issues: ImageIssue[];
   images: ImageInfo[];
 }
+
+interface DeliverabilityReport {
+  domain: string;
+  checks: DeliverabilityCheck[];
+  score: number;       // 0-100
+  issues: DeliverabilityIssue[];
+}
+
+interface DeliverabilityCheck {
+  name: "spf" | "dkim" | "dmarc" | "mx" | "bimi";
+  status: "pass" | "fail" | "warn" | "skip";
+  message: string;
+  detail?: string;
+  record?: string;
+}
+
+interface SpamAssassinResult {
+  score: number;
+  threshold: number;
+  isSpam: boolean;
+  rules: Array<{ name: string; score: number; description: string }>;
+  rawOutput: string;
+}
 ```
 
 ## Testing
@@ -605,7 +674,7 @@ interface ImageReport {
 bun test
 ```
 
-525 tests covering analysis, transformation, dark mode simulation, framework-aware fixes, AI fix generation, token estimation, spam scoring, link validation, accessibility checking, image analysis, inbox preview extraction, size checking, template variable detection, session API, security hardening, integration pipelines, and accuracy benchmarks.
+574 tests covering analysis (250+ CSS properties), transformation, dark mode simulation, framework-aware fixes, AI fix generation, token estimation, content hygiene scoring, link validation, accessibility checking, image analysis, inbox preview extraction, size checking, template variable detection, DNS deliverability checking, session API, security hardening, integration pipelines, accuracy benchmarks, and battle tests.
 
 ## License
 

package/dist/{chunk-ZQF2XUIJ.js → chunk-2NMEKWO5.js}

@@ -30,20 +30,9 @@ var __objRest = (source, exclude) => {
   return target;
 };
 
-// src/compile/errors.ts
-var CompileError = class extends Error {
-  constructor(message, format, phase) {
-    super(message);
-    this.name = "CompileError";
-    this.format = format;
-    this.phase = phase;
-  }
-};
-
 export {
   __spreadValues,
   __spreadProps,
-  __objRest,
-  CompileError
+  __objRest
 };
-//# sourceMappingURL=chunk-ZQF2XUIJ.js.map
+//# sourceMappingURL=chunk-2NMEKWO5.js.map

package/dist/{chunk-3NDQOTPM.js → chunk-E4QE4WXE.js}

@@ -1,6 +1,6 @@
 import {
   CompileError
-} from "./chunk-ZQF2XUIJ.js";
+} from "./chunk-Z22AD2IU.js";
 
 // src/compile/mjml.ts
 var MAX_SOURCE_SIZE = 512e3;
@@ -61,4 +61,4 @@ async function compileMjml(source) {
 export {
   compileMjml
 };
-//# sourceMappingURL=chunk-3NDQOTPM.js.map
+//# sourceMappingURL=chunk-E4QE4WXE.js.map

package/dist/{chunk-URZ4XPST.js → chunk-HBKZMR7V.js}

@@ -1,6 +1,6 @@
 import {
   CompileError
-} from "./chunk-ZQF2XUIJ.js";
+} from "./chunk-Z22AD2IU.js";
 
 // src/compile/react-email.ts
 var MAX_SOURCE_SIZE = 256e3;
@@ -356,4 +356,4 @@ async function executeInQuickJs(code, React, ReactEmailComponents) {
 export {
   compileReactEmail
 };
-//# sourceMappingURL=chunk-URZ4XPST.js.map
+//# sourceMappingURL=chunk-HBKZMR7V.js.map

package/dist/{chunk-OY3DGZVU.js → chunk-PW6EUG2G.js}

@@ -1,6 +1,6 @@
 import {
   CompileError
-} from "./chunk-ZQF2XUIJ.js";
+} from "./chunk-Z22AD2IU.js";
 
 // src/compile/maizzle.ts
 var MAX_SOURCE_SIZE = 512e3;
@@ -75,4 +75,4 @@ async function compileMaizzle(source) {
 export {
   compileMaizzle
 };
-//# sourceMappingURL=chunk-OY3DGZVU.js.map
+//# sourceMappingURL=chunk-PW6EUG2G.js.map

package/dist/chunk-Z22AD2IU.js

@@ -0,0 +1,14 @@
+// src/compile/errors.ts
+var CompileError = class extends Error {
+  constructor(message, format, phase) {
+    super(message);
+    this.name = "CompileError";
+    this.format = format;
+    this.phase = phase;
+  }
+};
+
+export {
+  CompileError
+};
+//# sourceMappingURL=chunk-Z22AD2IU.js.map

package/dist/{chunk-ZQF2XUIJ.js.map → chunk-Z22AD2IU.js.map}

@@ -1 +1 @@
-{"version":3,"sources":["../src/compile/errors.ts"],"sourcesContent":["import type { InputFormat } from \"../types.js\";\r\n\r\n/**\r\n * Unified error class for all email compilation failures.\r\n *\r\n * Replaces the per-format error classes (ReactEmailCompileError,\r\n * MjmlCompileError, MaizzleCompileError) with a single class that\r\n * carries the source format and failure phase.\r\n */\r\nexport class CompileError extends Error {\r\n  override name = \"CompileError\";\r\n  readonly format: Exclude<InputFormat, \"html\">;\r\n  readonly phase: \"validation\" | \"transpile\" | \"execution\" | \"render\" | \"compile\";\r\n\r\n  constructor(\r\n    message: string,\r\n    format: CompileError[\"format\"],\r\n    phase: CompileError[\"phase\"],\r\n  ) {\r\n    super(message);\r\n    this.format = format;\r\n    this.phase = phase;\r\n  }\r\n}\r\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AASO,IAAM,eAAN,cAA2B,MAAM;AAAA,EAKtC,YACE,SACA,QACA,OACA;AACA,UAAM,OAAO;AATf,SAAS,OAAO;AAUd,SAAK,SAAS;AACd,SAAK,QAAQ;AAAA,EACf;AACF;","names":[]}
+{"version":3,"sources":["../src/compile/errors.ts"],"sourcesContent":["import type { InputFormat } from \"../types.js\";\r\n\r\n/**\r\n * Unified error class for all email compilation failures.\r\n *\r\n * Replaces the per-format error classes (ReactEmailCompileError,\r\n * MjmlCompileError, MaizzleCompileError) with a single class that\r\n * carries the source format and failure phase.\r\n */\r\nexport class CompileError extends Error {\r\n  override name = \"CompileError\";\r\n  readonly format: Exclude<InputFormat, \"html\">;\r\n  readonly phase: \"validation\" | \"transpile\" | \"execution\" | \"render\" | \"compile\";\r\n\r\n  constructor(\r\n    message: string,\r\n    format: CompileError[\"format\"],\r\n    phase: CompileError[\"phase\"],\r\n  ) {\r\n    super(message);\r\n    this.format = format;\r\n    this.phase = phase;\r\n  }\r\n}\r\n"],"mappings":";AASO,IAAM,eAAN,cAA2B,MAAM;AAAA,EAKtC,YACE,SACA,QACA,OACA;AACA,UAAM,OAAO;AATf,SAAS,OAAO;AAUd,SAAK,SAAS;AACd,SAAK,QAAQ;AAAA,EACf;AACF;","names":[]}

package/dist/compile/index.d.cts

@@ -1,5 +1,5 @@
-import { s as InputFormat } from '../react-email-CYOtHJch.cjs';
-export { k as CompileError, l as CompileReactEmailOptions, u as SandboxStrategy, K as compileReactEmail } from '../react-email-CYOtHJch.cjs';
+import { u as InputFormat } from '../types-4P9AtKm_.cjs';
+export { C as CompileError, a as CompileReactEmailOptions, S as SandboxStrategy, c as compileReactEmail } from '../react-email-C-p8ZL37.cjs';
 
 /**
  * Compile an MJML source string into an HTML email string.

package/dist/compile/index.d.ts

@@ -1,5 +1,5 @@
-import { s as InputFormat } from '../react-email-CYOtHJch.js';
-export { k as CompileError, l as CompileReactEmailOptions, u as SandboxStrategy, K as compileReactEmail } from '../react-email-CYOtHJch.js';
+import { u as InputFormat } from '../types-4P9AtKm_.js';
+export { C as CompileError, a as CompileReactEmailOptions, S as SandboxStrategy, c as compileReactEmail } from '../react-email-DcseUoOu.js';
 
 /**
  * Compile an MJML source string into an HTML email string.

package/dist/compile/index.js

@@ -1,15 +1,16 @@
 import {
   compileReactEmail
-} from "../chunk-URZ4XPST.js";
+} from "../chunk-HBKZMR7V.js";
 import {
   compileMjml
-} from "../chunk-3NDQOTPM.js";
+} from "../chunk-E4QE4WXE.js";
 import {
   compileMaizzle
-} from "../chunk-OY3DGZVU.js";
+} from "../chunk-PW6EUG2G.js";
 import {
   CompileError
-} from "../chunk-ZQF2XUIJ.js";
+} from "../chunk-Z22AD2IU.js";
+import "../chunk-2NMEKWO5.js";
 
 // src/compile/index.ts
 import { extname } from "path";
@@ -18,15 +19,15 @@ async function compile(source, format, filePath) {
     case "html":
       return source;
     case "jsx": {
-      const { compileReactEmail: compileReactEmail2 } = await import("../react-email-4TW6IDAA.js");
+      const { compileReactEmail: compileReactEmail2 } = await import("../react-email-QKHRTEJW.js");
       return compileReactEmail2(source);
     }
     case "mjml": {
-      const { compileMjml: compileMjml2 } = await import("../mjml-D7IOYXXK.js");
+      const { compileMjml: compileMjml2 } = await import("../mjml-C46UWTTK.js");
       return compileMjml2(source);
     }
     case "maizzle": {
-      const { compileMaizzle: compileMaizzle2 } = await import("../maizzle-Y2CLJ7GB.js");
+      const { compileMaizzle: compileMaizzle2 } = await import("../maizzle-KKJF7XY7.js");
       return compileMaizzle2(source);
     }
     default:

package/dist/compile/index.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../../src/compile/index.ts"],"sourcesContent":["import { extname } from \"node:path\";\r\nimport type { InputFormat } from \"../types.js\";\r\n\r\nexport { CompileError } from \"./errors.js\";\r\nexport { compileReactEmail } from \"./react-email.js\";\r\nexport type { SandboxStrategy, CompileReactEmailOptions } from \"./react-email.js\";\r\nexport { compileMjml } from \"./mjml.js\";\r\nexport { compileMaizzle } from \"./maizzle.js\";\r\n\r\n/**\r\n * Compile source to HTML based on format.\r\n * Returns the HTML unchanged if format is \"html\".\r\n * Lazily imports per-format compilers to avoid loading unnecessary deps.\r\n */\r\nexport async function compile(\r\n  source: string,\r\n  format: InputFormat,\r\n  filePath?: string,\r\n): Promise<string> {\r\n  switch (format) {\r\n    case \"html\":\r\n      return source;\r\n\r\n    case \"jsx\": {\r\n      const { compileReactEmail } = await import(\"./react-email.js\");\r\n      return compileReactEmail(source);\r\n    }\r\n\r\n    case \"mjml\": {\r\n      const { compileMjml } = await import(\"./mjml.js\");\r\n      return compileMjml(source);\r\n    }\r\n\r\n    case \"maizzle\": {\r\n      const { compileMaizzle } = await import(\"./maizzle.js\");\r\n      return compileMaizzle(source);\r\n    }\r\n\r\n    default:\r\n      throw new Error(`Unknown format: \"${format}\". Use html, jsx, mjml, or maizzle.`);\r\n  }\r\n}\r\n\r\n/**\r\n * Auto-detect input format from file extension.\r\n */\r\nexport function detectFormat(filePath: string): InputFormat {\r\n  const ext = extname(filePath).toLowerCase();\r\n\r\n  switch (ext) {\r\n    case \".tsx\":\r\n    case \".jsx\":\r\n      return \"jsx\";\r\n    case \".mjml\":\r\n      return \"mjml\";\r\n    case \".html\":\r\n    case \".htm\":\r\n      return \"html\";\r\n    default:\r\n      return \"html\";\r\n  }\r\n}\r\n"],"mappings":";;;;;;;;;;;;;;AAAA,SAAS,eAAe;AAcxB,eAAsB,QACpB,QACA,QACA,UACiB;AACjB,UAAQ,QAAQ;AAAA,IACd,KAAK;AACH,aAAO;AAAA,IAET,KAAK,OAAO;AACV,YAAM,EAAE,mBAAAA,mBAAkB,IAAI,MAAM,OAAO,4BAAkB;AAC7D,aAAOA,mBAAkB,MAAM;AAAA,IACjC;AAAA,IAEA,KAAK,QAAQ;AACX,YAAM,EAAE,aAAAC,aAAY,IAAI,MAAM,OAAO,qBAAW;AAChD,aAAOA,aAAY,MAAM;AAAA,IAC3B;AAAA,IAEA,KAAK,WAAW;AACd,YAAM,EAAE,gBAAAC,gBAAe,IAAI,MAAM,OAAO,wBAAc;AACtD,aAAOA,gBAAe,MAAM;AAAA,IAC9B;AAAA,IAEA;AACE,YAAM,IAAI,MAAM,oBAAoB,MAAM,qCAAqC;AAAA,EACnF;AACF;AAKO,SAAS,aAAa,UAA+B;AAC1D,QAAM,MAAM,QAAQ,QAAQ,EAAE,YAAY;AAE1C,UAAQ,KAAK;AAAA,IACX,KAAK;AAAA,IACL,KAAK;AACH,aAAO;AAAA,IACT,KAAK;AACH,aAAO;AAAA,IACT,KAAK;AAAA,IACL,KAAK;AACH,aAAO;AAAA,IACT;AACE,aAAO;AAAA,EACX;AACF;","names":["compileReactEmail","compileMjml","compileMaizzle"]}
+{"version":3,"sources":["../../src/compile/index.ts"],"sourcesContent":["import { extname } from \"node:path\";\r\nimport type { InputFormat } from \"../types.js\";\r\n\r\nexport { CompileError } from \"./errors.js\";\r\nexport { compileReactEmail } from \"./react-email.js\";\r\nexport type { SandboxStrategy, CompileReactEmailOptions } from \"./react-email.js\";\r\nexport { compileMjml } from \"./mjml.js\";\r\nexport { compileMaizzle } from \"./maizzle.js\";\r\n\r\n/**\r\n * Compile source to HTML based on format.\r\n * Returns the HTML unchanged if format is \"html\".\r\n * Lazily imports per-format compilers to avoid loading unnecessary deps.\r\n */\r\nexport async function compile(\r\n  source: string,\r\n  format: InputFormat,\r\n  filePath?: string,\r\n): Promise<string> {\r\n  switch (format) {\r\n    case \"html\":\r\n      return source;\r\n\r\n    case \"jsx\": {\r\n      const { compileReactEmail } = await import(\"./react-email.js\");\r\n      return compileReactEmail(source);\r\n    }\r\n\r\n    case \"mjml\": {\r\n      const { compileMjml } = await import(\"./mjml.js\");\r\n      return compileMjml(source);\r\n    }\r\n\r\n    case \"maizzle\": {\r\n      const { compileMaizzle } = await import(\"./maizzle.js\");\r\n      return compileMaizzle(source);\r\n    }\r\n\r\n    default:\r\n      throw new Error(`Unknown format: \"${format}\". Use html, jsx, mjml, or maizzle.`);\r\n  }\r\n}\r\n\r\n/**\r\n * Auto-detect input format from file extension.\r\n */\r\nexport function detectFormat(filePath: string): InputFormat {\r\n  const ext = extname(filePath).toLowerCase();\r\n\r\n  switch (ext) {\r\n    case \".tsx\":\r\n    case \".jsx\":\r\n      return \"jsx\";\r\n    case \".mjml\":\r\n      return \"mjml\";\r\n    case \".html\":\r\n    case \".htm\":\r\n      return \"html\";\r\n    default:\r\n      return \"html\";\r\n  }\r\n}\r\n"],"mappings":";;;;;;;;;;;;;;;AAAA,SAAS,eAAe;AAcxB,eAAsB,QACpB,QACA,QACA,UACiB;AACjB,UAAQ,QAAQ;AAAA,IACd,KAAK;AACH,aAAO;AAAA,IAET,KAAK,OAAO;AACV,YAAM,EAAE,mBAAAA,mBAAkB,IAAI,MAAM,OAAO,4BAAkB;AAC7D,aAAOA,mBAAkB,MAAM;AAAA,IACjC;AAAA,IAEA,KAAK,QAAQ;AACX,YAAM,EAAE,aAAAC,aAAY,IAAI,MAAM,OAAO,qBAAW;AAChD,aAAOA,aAAY,MAAM;AAAA,IAC3B;AAAA,IAEA,KAAK,WAAW;AACd,YAAM,EAAE,gBAAAC,gBAAe,IAAI,MAAM,OAAO,wBAAc;AACtD,aAAOA,gBAAe,MAAM;AAAA,IAC9B;AAAA,IAEA;AACE,YAAM,IAAI,MAAM,oBAAoB,MAAM,qCAAqC;AAAA,EACnF;AACF;AAKO,SAAS,aAAa,UAA+B;AAC1D,QAAM,MAAM,QAAQ,QAAQ,EAAE,YAAY;AAE1C,UAAQ,KAAK;AAAA,IACX,KAAK;AAAA,IACL,KAAK;AACH,aAAO;AAAA,IACT,KAAK;AACH,aAAO;AAAA,IACT,KAAK;AAAA,IACL,KAAK;AACH,aAAO;AAAA,IACT;AACE,aAAO;AAAA,EACX;AACF;","names":["compileReactEmail","compileMjml","compileMaizzle"]}