@emailens/engine 0.3.0 → 0.3.1

package/dist/index.d.ts

@@ -171,6 +171,12 @@ interface SpamReport {
     level: "low" | "medium" | "high";
     issues: SpamIssue[];
 }
+interface SpamAnalysisOptions {
+    /** Value of the List-Unsubscribe header, if present */
+    listUnsubscribeHeader?: string;
+    /** Type of email — transactional emails are exempt from unsubscribe requirements */
+    emailType?: "marketing" | "transactional";
+}
 interface LinkIssue {
     severity: "error" | "warning" | "info";
     rule: string;
@@ -378,11 +384,11 @@ declare const STRUCTURAL_FIX_PROPERTIES: Set<string>;
 /**
  * Analyze an HTML email for spam indicators.
  *
- * Returns a 0–100 score (100 = clean, 0 = very spammy) and an array
+ * Returns a 0-100 score (100 = clean, 0 = very spammy) and an array
  * of issues found. Uses heuristic rules modeled after common spam
  * filter triggers (CAN-SPAM, GDPR, SpamAssassin patterns).
  */
-declare function analyzeSpam(html: string): SpamReport;
+declare function analyzeSpam(html: string, options?: SpamAnalysisOptions): SpamReport;
 
 /**
  * Extract and validate all links from an HTML email.
@@ -411,4 +417,4 @@ declare function checkAccessibility(html: string): AccessibilityReport;
  */
 declare function analyzeImages(html: string): ImageReport;
 
-export { AI_FIX_SYSTEM_PROMPT, type AccessibilityIssue, type AccessibilityReport, type AiFixResult, type AiProvider, type CSSWarning, type CodeFix, type DiffResult, EMAIL_CLIENTS, type EmailClient, type EstimateOptions, type ExportPromptOptions, type ExportScope, type FixType, type Framework, type GenerateAiFixOptions, type ImageInfo, type ImageIssue, type ImageReport, type InputFormat, type LinkIssue, type LinkReport, type PreviewResult, STRUCTURAL_FIX_PROPERTIES, type SpamIssue, type SpamReport, type SupportLevel, type TokenEstimate, type TokenEstimateWithWarnings, type TransformResult, analyzeEmail, analyzeImages, analyzeSpam, checkAccessibility, diffResults, estimateAiFixTokens, generateAiFix, generateCompatibilityScore, generateFixPrompt, getClient, getCodeFix, getSuggestion, heuristicTokenCount, simulateDarkMode, transformForAllClients, transformForClient, validateLinks };
+export { AI_FIX_SYSTEM_PROMPT, type AccessibilityIssue, type AccessibilityReport, type AiFixResult, type AiProvider, type CSSWarning, type CodeFix, type DiffResult, EMAIL_CLIENTS, type EmailClient, type EstimateOptions, type ExportPromptOptions, type ExportScope, type FixType, type Framework, type GenerateAiFixOptions, type ImageInfo, type ImageIssue, type ImageReport, type InputFormat, type LinkIssue, type LinkReport, type PreviewResult, STRUCTURAL_FIX_PROPERTIES, type SpamAnalysisOptions, type SpamIssue, type SpamReport, type SupportLevel, type TokenEstimate, type TokenEstimateWithWarnings, type TransformResult, analyzeEmail, analyzeImages, analyzeSpam, checkAccessibility, diffResults, estimateAiFixTokens, generateAiFix, generateCompatibilityScore, generateFixPrompt, getClient, getCodeFix, getSuggestion, heuristicTokenCount, simulateDarkMode, transformForAllClients, transformForClient, validateLinks };

package/dist/index.js

@@ -3949,6 +3949,15 @@ var SPAM_TRIGGER_PHRASES = [
   "no strings attached",
   "no questions asked"
 ];
+function escapeRegex(s) {
+  return s.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+var SPAM_PHRASE_PATTERNS = new Map(
+  SPAM_TRIGGER_PHRASES.map((phrase) => [
+    phrase,
+    new RegExp("\\b" + escapeRegex(phrase) + "\\b")
+  ])
+);
 var URL_SHORTENERS = [
   "bit.ly",
   "tinyurl.com",
@@ -3963,6 +3972,46 @@ var URL_SHORTENERS = [
   "cutt.ly",
   "rb.gy"
 ];
+var ESP_TRACKING_DOMAINS = [
+  "mailchi.mp",
+  "list-manage.com",
+  "click.mailchimp.com",
+  "sendgrid.net",
+  "click.sendgrid.net",
+  "ct.sendgrid.net",
+  "click.klaviyomail.com",
+  "trk.klaviyo.com",
+  "click.hubspotemail.net",
+  "links.iterable.com",
+  "track.customer.io",
+  "go.pardot.com",
+  "mailgun.org",
+  "em.salesforce.com",
+  "click.marketingcloud.com",
+  "r.mail.yahoo.com",
+  "t.dripemail2.com"
+];
+var TRANSACTIONAL_SIGNALS = [
+  "reset your password",
+  "password reset",
+  "verify your email",
+  "email verification",
+  "order confirmation",
+  "your order",
+  "your receipt",
+  "purchase confirmation",
+  "verification code",
+  "confirm your account",
+  "your invoice",
+  "shipping confirmation",
+  "account activation",
+  "security alert"
+];
+var TRANSACTIONAL_SIGNAL_PATTERN = new RegExp(
+  TRANSACTIONAL_SIGNALS.map(escapeRegex).join("|"),
+  "i"
+);
+var OTP_PATTERN = /\b\d{4,8}\b/;
 var WEIGHTS = {
   "caps-ratio": 15,
   "excessive-punctuation": 10,
@@ -3997,9 +4046,10 @@ function checkCapsRatio(text) {
 }
 function checkExcessivePunctuation(text) {
   const exclamations = (text.match(/!/g) || []).length;
-  const dollars = (text.match(/\$/g) || []).length;
+  const dollars = (text.match(/\$(?!\d)/g) || []).length;
   const total = exclamations + dollars;
-  if (total > 5) {
+  const threshold = Math.max(5, Math.floor(text.length / 200));
+  if (total > threshold) {
     return {
       rule: "excessive-punctuation",
       severity: "warning",
@@ -4011,8 +4061,8 @@ function checkExcessivePunctuation(text) {
 function checkSpamPhrases(text) {
   const lower = text.toLowerCase();
   const found = [];
-  for (const phrase of SPAM_TRIGGER_PHRASES) {
-    if (lower.includes(phrase)) {
+  for (const [phrase, pattern] of SPAM_PHRASE_PATTERNS) {
+    if (pattern.test(lower)) {
       found.push({
         rule: "spam-phrases",
         severity: "info",
@@ -4022,16 +4072,33 @@ function checkSpamPhrases(text) {
   }
   return found;
 }
-function checkUnsubscribe($) {
+function checkUnsubscribe($, text, options) {
+  var _a;
+  if ((options == null ? void 0 : options.emailType) === "transactional") return null;
+  if ((_a = options == null ? void 0 : options.listUnsubscribeHeader) == null ? void 0 : _a.trim()) return null;
   let hasUnsubscribe = false;
   $("a").each((_, el) => {
     const href = $(el).attr("href") || "";
-    const text = $(el).text().toLowerCase();
-    if (text.includes("unsubscribe") || href.toLowerCase().includes("unsubscribe") || text.includes("opt out") || text.includes("opt-out") || href.toLowerCase().includes("opt-out") || href.toLowerCase().includes("optout")) {
+    const linkText = $(el).text().toLowerCase();
+    if (linkText.includes("unsubscribe") || href.toLowerCase().includes("unsubscribe") || linkText.includes("opt out") || linkText.includes("opt-out") || href.toLowerCase().includes("opt-out") || href.toLowerCase().includes("optout")) {
       hasUnsubscribe = true;
     }
   });
   if (!hasUnsubscribe) {
+    const lower = text.toLowerCase();
+    const signalMatches = TRANSACTIONAL_SIGNALS.filter(
+      (s) => lower.includes(s.toLowerCase())
+    );
+    const hasOtp = OTP_PATTERN.test(text);
+    const signalCount = signalMatches.length + (hasOtp ? 1 : 0);
+    if (signalCount >= 2) {
+      return {
+        rule: "missing-unsubscribe",
+        severity: "info",
+        message: "No unsubscribe link found, but email appears transactional \u2014 may not be required.",
+        detail: `Detected transactional signals: ${signalMatches.join(", ")}${hasOtp ? ", OTP code" : ""}`
+      };
+    }
     return {
       rule: "missing-unsubscribe",
       severity: "error",
@@ -4041,6 +4108,18 @@ function checkUnsubscribe($) {
   }
   return null;
 }
+var PREHEADER_ACCESSORY_PATTERNS = [
+  /max-height\s*:\s*0/,
+  /overflow\s*:\s*hidden/,
+  /mso-hide\s*:\s*all/,
+  /opacity\s*:\s*0/,
+  /color\s*:\s*transparent/,
+  /line-height\s*:\s*0/
+];
+function isLikelyPreheader(style, text) {
+  if (text.length > 200) return false;
+  return PREHEADER_ACCESSORY_PATTERNS.some((p) => p.test(style));
+}
 function checkHiddenText($) {
   let found = false;
   let detail = "";
@@ -4048,20 +4127,24 @@ function checkHiddenText($) {
     const style = ($(el).attr("style") || "").toLowerCase();
     const text = $(el).text().trim();
     if (!text) return;
-    if (/font-size\s*:\s*0(?:px|em|rem|pt)?(?:\s|;|$)/.test(style)) {
-      found = true;
-      detail = "font-size:0 on element with text content";
-      return false;
-    }
     if (/visibility\s*:\s*hidden/.test(style)) {
       found = true;
       detail = "visibility:hidden on element with text content";
       return false;
     }
+    if (/font-size\s*:\s*0(?:px|em|rem|pt)?(?:\s|;|$)/.test(style)) {
+      if (!isLikelyPreheader(style, text)) {
+        found = true;
+        detail = "font-size:0 on element with text content";
+        return false;
+      }
+    }
     if (/display\s*:\s*none/.test(style)) {
-      found = true;
-      detail = "display:none on element with text content";
-      return false;
+      if (!isLikelyPreheader(style, text)) {
+        found = true;
+        detail = "display:none on element with text content";
+        return false;
+      }
     }
   });
   if (found) {
@@ -4079,8 +4162,14 @@ function checkUrlShorteners($) {
   const seen = /* @__PURE__ */ new Set();
   $("a[href]").each((_, el) => {
     const href = $(el).attr("href") || "";
+    let hostname;
+    try {
+      hostname = new URL(href).hostname.toLowerCase();
+    } catch (e) {
+      return;
+    }
     for (const shortener of URL_SHORTENERS) {
-      if (href.includes(shortener) && !seen.has(shortener)) {
+      if ((hostname === shortener || hostname.endsWith("." + shortener)) && !seen.has(shortener)) {
         seen.add(shortener);
         issues.push({
           rule: "url-shortener",
@@ -4093,8 +4182,7 @@ function checkUrlShorteners($) {
   });
   return issues;
 }
-function checkImageToTextRatio($) {
-  const text = extractVisibleText($);
+function checkImageToTextRatio($, text) {
   const images = $("img").length;
   if (images === 0) return null;
   if (text.length < 50 && images > 0) {
@@ -4114,6 +4202,15 @@ function checkImageToTextRatio($) {
   }
   return null;
 }
+function isEspTrackingDomain(hostname) {
+  return ESP_TRACKING_DOMAINS.some(
+    (esp) => hostname === esp || hostname.endsWith("." + esp)
+  );
+}
+function hasEncodedDestination(href, textDomain) {
+  const encoded = encodeURIComponent(textDomain);
+  return href.includes(encoded) || href.includes(textDomain);
+}
 function checkDeceptiveLinks($) {
   const issues = [];
   $("a[href]").each((_, el) => {
@@ -4126,6 +4223,8 @@ function checkDeceptiveLinks($) {
         ).hostname.replace(/^www\./, "");
         const hrefDomain = new URL(href).hostname.replace(/^www\./, "");
         if (textDomain !== hrefDomain) {
+          if (isEspTrackingDomain(hrefDomain)) return;
+          if (hasEncodedDestination(href, textDomain)) return;
           issues.push({
             rule: "deceptive-link",
             severity: "error",
@@ -4151,7 +4250,7 @@ function checkAllCapsTitle($) {
   }
   return null;
 }
-function analyzeSpam(html) {
+function analyzeSpam(html, options) {
   if (!html || !html.trim()) {
     return { score: 100, level: "low", issues: [] };
   }
@@ -4163,12 +4262,12 @@ function analyzeSpam(html) {
   const punctIssue = checkExcessivePunctuation(text);
   if (punctIssue) issues.push(punctIssue);
   issues.push(...checkSpamPhrases(text));
-  const unsubIssue = checkUnsubscribe($);
+  const unsubIssue = checkUnsubscribe($, text, options);
   if (unsubIssue) issues.push(unsubIssue);
   const hiddenIssue = checkHiddenText($);
   if (hiddenIssue) issues.push(hiddenIssue);
   issues.push(...checkUrlShorteners($));
-  const imageRatioIssue = checkImageToTextRatio($);
+  const imageRatioIssue = checkImageToTextRatio($, text);
   if (imageRatioIssue) issues.push(imageRatioIssue);
   issues.push(...checkDeceptiveLinks($));
   const capsTitle = checkAllCapsTitle($);
@@ -4184,7 +4283,9 @@ function analyzeSpam(html) {
     } else if (issue.rule === "url-shortener" || issue.rule === "deceptive-link") {
       if (count <= 2) penalty += weight;
     } else {
-      penalty += weight;
+      if (issue.severity !== "info") {
+        penalty += weight;
+      }
     }
   }
   const score = Math.max(0, Math.min(100, 100 - penalty));