@emailcheck/email-validator-js 3.4.4 → 4.0.0-beta.1

package/README.md

@@ -91,7 +91,7 @@ pnpm add @emailcheck/email-validator-js
 ```
 
 ### Requirements (consumers)
-- Node.js >= 18 (runtime target — the published bundle is plain Node.js + ESM/CJS)
+- Node.js >= 22 (currently-supported LTS lines: 22 Maintenance, 24 Active)
 - TypeScript >= 4.0 (for TypeScript users)
 
 ### Requirements (contributing)
@@ -864,7 +864,7 @@ bun run examples/high-level/advanced-usage.ts
 bun run examples/integrations/algolia.ts
 ```
 
-**After installation in your own project (Node 20.10+):**
+**After installation in your own project (Node 22+):**
 
 ```bash
 node --experimental-strip-types examples/smtp/usage.ts
@@ -1386,7 +1386,7 @@ app.http('validateEmail', {
 
 ### Edge MX support via the built-in DoH resolver
 
-A built-in `DoHResolver` ships with the package — works in any runtime with `fetch` (Cloudflare Workers, Vercel Edge, Deno, browsers, Node 18+):
+A built-in `DoHResolver` ships with the package — works in any runtime with `fetch` (Cloudflare Workers, Vercel Edge, Deno, browsers, Node 22+):
 
 ```typescript
 import {

package/dist/cache-interface.d.ts

@@ -5,9 +5,11 @@
 import type { DisposableEmailResult, DomainValidResult, FreeEmailResult, SmtpVerificationResult } from './types';
 import type { ParsedWhoisResult } from './whois-parser';
 /**
- * Generic cache interface that can be implemented by any cache store
+ * Generic cache interface that can be implemented by any cache store.
+ * Default type parameter is `unknown` — callers should narrow it
+ * (`CacheStore<DisposableEmailResult>`) rather than relying on the default.
  */
-export interface CacheStore<T = any> {
+export interface CacheStore<T = unknown> {
     /**
      * Get a value from cache
      * @param key - The cache key

package/dist/cli/index.js

@@ -7,6 +7,7 @@ var tinyLru = require('tiny-lru');
 var psl = require('psl');
 var stringSimilarityJs = require('string-similarity-js');
 var node_dns = require('node:dns');
+var node_crypto = require('node:crypto');
 var net$1 = require('node:net');
 var tls = require('node:tls');
 
@@ -313,16 +314,6 @@ var VerificationErrorCode = /* @__PURE__ */ ((VerificationErrorCode2) => {
   VerificationErrorCode2["freeEmailProvider"] = "FREE_EMAIL_PROVIDER";
   return VerificationErrorCode2;
 })(VerificationErrorCode || {});
-var EmailProvider = /* @__PURE__ */ ((EmailProvider2) => {
-  EmailProvider2["gmail"] = "gmail";
-  EmailProvider2["hotmailB2b"] = "hotmail_b2b";
-  EmailProvider2["hotmailB2c"] = "hotmail_b2c";
-  EmailProvider2["proofpoint"] = "proofpoint";
-  EmailProvider2["mimecast"] = "mimecast";
-  EmailProvider2["yahoo"] = "yahoo";
-  EmailProvider2["everythingElse"] = "everything_else";
-  return EmailProvider2;
-})(EmailProvider || {});
 var SMTPStep = /* @__PURE__ */ ((SMTPStep2) => {
   SMTPStep2["greeting"] = "GREETING";
   SMTPStep2["ehlo"] = "EHLO";
@@ -765,9 +756,9 @@ function parseCompositeNamePart(part) {
         cleaned = pureAlpha;
         confidence = 0.6;
       } else {
-        const baseMatch2 = part.match(/^([a-zA-Z]+)\d*$/);
-        if (baseMatch2) {
-          cleaned = baseMatch2[1];
+        const baseMatch = part.match(/^([a-zA-Z]+)\d*$/);
+        if (baseMatch) {
+          cleaned = baseMatch[1];
           confidence = 0.75;
         } else {
           cleaned = part;
@@ -781,9 +772,7 @@ function parseCompositeNamePart(part) {
       confidence = Math.min(1, confidence + 0.2);
     }
   }
-  const baseMatch = part.match(/^([a-zA-Z]+[a-zA-Z0-9]*?)\d*$/);
-  const base = baseMatch ? baseMatch[1] : part;
-  return { base, hasNumbers, cleaned, confidence };
+  return { hasNumbers, cleaned, confidence };
 }
 function isLikelyName(str, allowNumbers = false, allowSingleLetter = false) {
   if (!str) return false;
@@ -1037,6 +1026,9 @@ function parseDsn(reply) {
   if (!match) return null;
   return { class: Number(match[1]), subject: Number(match[2]), detail: Number(match[3]) };
 }
+function dsnToString(dsn) {
+  return `${dsn.class}.${dsn.subject}.${dsn.detail}`;
+}
 function isPolicyBlock(reply) {
   const dsn = parseDsn(reply);
   return dsn?.class === 5 && dsn?.subject === 7;
@@ -1054,6 +1046,9 @@ function isInvalidMailboxError(reply) {
   if (isPolicyBlock(reply)) return false;
   return true;
 }
+function defaultProbeLocal() {
+  return `${node_crypto.randomBytes(8).toString("hex")}-noexist`;
+}
 async function verifyMailboxSMTP(params) {
   const { local, domain, options = {} } = params;
   const mxRecords = params.mxRecords ?? [];
@@ -1067,16 +1062,29 @@ async function verifyMailboxSMTP(params) {
   const cache = options.cache;
   const log = debug ? (...args) => console.log("[SMTP]", ...args) : () => {
   };
-  const mxHost = mxRecords[0];
-  if (!mxHost) {
+  const startedAtMs = Date.now();
+  const primaryMx = mxRecords[0];
+  if (!primaryMx) {
     log("No MX records found");
-    return { smtpResult: failureResult("No MX records found"), cached: false, port: 0, portCached: false };
+    const metrics2 = makeMetrics([], 0, 0, void 0, startedAtMs);
+    return { smtpResult: failureResult("no_mx_records", metrics2), cached: false, port: 0, portCached: false };
   }
-  log(`Verifying ${local}@${domain} via ${mxHost}`);
+  log(`Verifying ${local}@${domain} via ${primaryMx} (mx count=${mxRecords.length})`);
   const transcript = [];
   const commands = [];
+  const probeOptions = {
+    local,
+    domain,
+    timeout,
+    tlsConfig,
+    hostname,
+    sequence,
+    log,
+    catchAllProbeLocal: options.catchAllProbeLocal,
+    pipelining: options.pipelining ?? "auto"
+  };
   const verdictCache = cache ? getCacheStore(cache, "smtp") : null;
-  const verdictKey = `${mxHost}:${local}@${domain}`;
+  const verdictKey = `${primaryMx}:${local}@${domain}`;
   if (verdictCache) {
     const cachedResult = await safeCacheGet(verdictCache, verdictKey);
     if (cachedResult) {
@@ -1085,81 +1093,91 @@ async function verifyMailboxSMTP(params) {
     }
   }
   const portCache = cache ? getCacheStore(cache, "smtpPort") : null;
-  if (portCache) {
-    const cachedPort = await safeCacheGet(portCache, mxHost);
-    if (cachedPort) {
-      log(`Using cached port: ${cachedPort}`);
-      const probe = await runProbe({
-        mxHost,
-        port: cachedPort,
-        local,
-        domain,
-        timeout,
-        tlsConfig,
-        hostname,
-        sequence,
-        log
-      });
-      collectTranscript(transcript, commands, probe, cachedPort);
-      const smtpResult = toSmtpVerificationResult(
-        probe.result,
-        captureTranscript ? { transcript, commands } : void 0
-      );
-      await safeCacheSet(verdictCache, verdictKey, smtpResult);
-      return { smtpResult, cached: false, port: cachedPort, portCached: true };
-    }
-  }
-  for (const port of ports) {
-    log(`Testing port ${port}`);
-    const probe = await runProbe({ mxHost, port, local, domain, timeout, tlsConfig, hostname, sequence, log });
-    collectTranscript(transcript, commands, probe, port);
-    const smtpResult = toSmtpVerificationResult(probe.result, captureTranscript ? { transcript, commands } : void 0);
-    await safeCacheSet(verdictCache, verdictKey, smtpResult);
-    if (probe.result !== null) {
-      await safeCacheSet(portCache, mxHost, port);
-      return { smtpResult, cached: false, port, portCached: false };
+  const cachedPort = portCache ? await safeCacheGet(portCache, primaryMx) : null;
+  const mxHostsTried = [];
+  let mxAttempts = 0;
+  let portAttempts = 0;
+  let lastReason = "all_attempts_failed";
+  let lastEnhancedStatus;
+  let lastResponseCode;
+  for (const mxHost of mxRecords) {
+    mxHostsTried.push(mxHost);
+    mxAttempts++;
+    const portsForThisMx = mxHost === primaryMx && cachedPort ? [cachedPort, ...ports.filter((p) => p !== cachedPort)] : ports;
+    for (const port of portsForThisMx) {
+      portAttempts++;
+      log(`Testing ${mxHost}:${port}`);
+      const probe = await runProbe({ ...probeOptions, mxHost, port });
+      collectTranscript(transcript, commands, probe, mxHost, port);
+      lastReason = probe.reason;
+      if (probe.enhancedStatus !== void 0) lastEnhancedStatus = probe.enhancedStatus;
+      if (probe.responseCode !== void 0) lastResponseCode = probe.responseCode;
+      if (probe.result !== null) {
+        const metrics2 = makeMetrics(mxHostsTried, mxAttempts, portAttempts, mxHost, startedAtMs);
+        const smtpResult2 = toSmtpVerificationResult(probe, {
+          transcript: captureTranscript ? transcript : void 0,
+          commands: captureTranscript ? commands : void 0,
+          metrics: metrics2
+        });
+        await safeCacheSet(verdictCache, verdictKey, smtpResult2);
+        if (mxHost === primaryMx) await safeCacheSet(portCache, primaryMx, port);
+        return { smtpResult: smtpResult2, cached: false, port, portCached: cachedPort === port };
+      }
     }
   }
-  log("All ports failed");
+  log(`All MX\xD7port attempts failed (mx=${mxAttempts}, port=${portAttempts})`);
+  const metrics = makeMetrics(mxHostsTried, mxAttempts, portAttempts, void 0, startedAtMs);
+  const smtpResult = {
+    ...failureResult(lastReason, metrics),
+    ...lastEnhancedStatus !== void 0 ? { enhancedStatus: lastEnhancedStatus } : {},
+    ...lastResponseCode !== void 0 ? { responseCode: lastResponseCode } : {},
+    ...captureTranscript ? { transcript: [...transcript], commands: [...commands] } : {}
+  };
+  return { smtpResult, cached: false, port: 0, portCached: false };
+}
+function makeMetrics(mxHostsTried, mxAttempts, portAttempts, mxHostUsed, startedAtMs) {
   return {
-    smtpResult: {
-      ...failureResult("All SMTP connection attempts failed"),
-      ...captureTranscript ? { transcript: [...transcript], commands: [...commands] } : {}
-    },
-    cached: false,
-    port: 0,
-    portCached: false
+    mxAttempts,
+    portAttempts,
+    mxHostsTried: [...mxHostsTried],
+    ...mxHostUsed !== void 0 ? { mxHostUsed } : {},
+    totalDurationMs: Date.now() - startedAtMs
   };
 }
-function collectTranscript(transcript, commands, probe, port) {
-  for (const line of probe.transcript) transcript.push(`${port}|s| ${line}`);
-  for (const cmd of probe.commands) commands.push(`${port}|c| ${cmd}`);
+function collectTranscript(transcript, commands, probe, mxHost, port) {
+  const prefix = `${mxHost}:${port}`;
+  for (const line of probe.transcript) transcript.push(`${prefix}|s| ${line}`);
+  for (const cmd of probe.commands) commands.push(`${prefix}|c| ${cmd}`);
 }
-function failureResult(error) {
+function failureResult(reason, metrics) {
   return {
     canConnectSmtp: false,
     hasFullInbox: false,
     isCatchAll: false,
     isDeliverable: false,
     isDisabled: false,
-    error,
-    providerUsed: EmailProvider.everythingElse,
-    checkedAt: Date.now()
+    error: reason,
+    checkedAt: Date.now(),
+    metrics
   };
 }
-function toSmtpVerificationResult(result, capture) {
-  const base = {
+function toSmtpVerificationResult(probe, extras) {
+  const result = probe.result;
+  const out = {
     canConnectSmtp: result !== null,
-    hasFullInbox: false,
-    isCatchAll: false,
+    hasFullInbox: probe.reason === "over_quota",
+    isCatchAll: probe.isCatchAll ?? false,
     isDeliverable: result === true,
     isDisabled: result === false,
-    error: result === true ? void 0 : result === null ? "ambiguous" : "not_found",
-    providerUsed: EmailProvider.everythingElse,
-    checkedAt: Date.now()
+    error: result === true ? void 0 : probe.reason,
+    checkedAt: Date.now(),
+    metrics: extras.metrics,
+    ...probe.enhancedStatus !== void 0 ? { enhancedStatus: probe.enhancedStatus } : {},
+    ...probe.responseCode !== void 0 ? { responseCode: probe.responseCode } : {}
   };
-  if (!capture) return base;
-  return { ...base, transcript: [...capture.transcript], commands: [...capture.commands] };
+  if (extras.transcript) out.transcript = [...extras.transcript];
+  if (extras.commands) out.commands = [...extras.commands];
+  return out;
 }
 async function safeCacheGet(store, key) {
   if (!store) return null;
@@ -1186,9 +1204,20 @@ class SMTPProbeConnection {
     this.buffer = "";
     this.resolved = false;
     this.currentStepIndex = 0;
-    /** Server lines + client commands captured unconditionally (cost is trivial). */
     this.transcript = [];
     this.commands = [];
+    // ── EHLO capability advertisement ────────────────────────────────────────
+    this.supportsPipelining = false;
+    this.dualPhase = "idle";
+    this.realOutcome = "pending";
+    this.probeOutcome = "pending";
+    this.dualPipelined = false;
+    /**
+     * Pipelined-only escape hatch. When the real RCPT is rejected mid-batched-
+     * envelope, the probe + RSET are already on the wire; we stash the verdict
+     * and commit it after the response loop drains.
+     */
+    this.pendingDecision = null;
     this.onData = (data) => {
       if (this.resolved) return;
       this.resetStepTimer();
@@ -1211,6 +1240,7 @@ class SMTPProbeConnection {
       minVersion: "TLSv1.2",
       ...typeof p.tlsConfig === "object" ? p.tlsConfig : {}
     };
+    this.probeLocal = p.catchAllProbeLocal ? p.catchAllProbeLocal(p.local, p.domain) : defaultProbeLocal();
   }
   run() {
     return new Promise((resolve) => {
@@ -1265,6 +1295,7 @@ class SMTPProbeConnection {
     switch (step) {
       case SMTPStep.greeting:
         return;
+      // server-driven; nothing to send
       case SMTPStep.ehlo:
         this.send(`EHLO ${this.p.hostname}`);
         return;
@@ -1277,37 +1308,82 @@ class SMTPProbeConnection {
         return;
       }
       case SMTPStep.rcptTo:
-        this.send(`RCPT TO:<${this.p.local}@${this.p.domain}>`);
+        this.executeEnvelope();
         return;
     }
   }
+  /**
+   * Send the dual-probe envelope (real RCPT + probe RCPT + RSET). Pipelined
+   * when the MX advertised PIPELINING (or `pipelining: 'force'`); sequential
+   * otherwise.
+   */
+  executeEnvelope() {
+    const wantsPipelining = this.p.pipelining === "force" || this.p.pipelining === "auto" && this.supportsPipelining;
+    const realCmd = `RCPT TO:<${this.p.local}@${this.p.domain}>`;
+    if (wantsPipelining) {
+      this.dualPipelined = true;
+      const probeCmd = `RCPT TO:<${this.probeLocal}@${this.p.domain}>`;
+      const rsetCmd = "RSET";
+      this.commands.push(realCmd, probeCmd, rsetCmd);
+      this.p.log(`\u2192 ${realCmd}`);
+      this.p.log(`\u2192 ${probeCmd}`);
+      this.p.log(`\u2192 ${rsetCmd}`);
+      this.socket?.write(`${realCmd}\r
+${probeCmd}\r
+${rsetCmd}\r
+`);
+      this.dualPhase = "rcpt_real";
+      return;
+    }
+    this.dualPipelined = false;
+    this.send(realCmd);
+    this.dualPhase = "rcpt_real";
+  }
   processLine(line) {
     if (this.resolved) return;
     this.transcript.push(line);
     this.p.log(`\u2190 ${line}`);
-    if (isHighVolume(line)) {
-      this.finish(true, "high_volume");
-      return;
-    }
-    if (isOverQuota(line)) {
-      this.finish(false, "over_quota");
-      return;
+    const codeStr = line.slice(0, 3);
+    const numericCode = /^\d{3}$/.test(codeStr) ? parseInt(codeStr, 10) : null;
+    if (numericCode !== null) this.lastResponseCode = numericCode;
+    const dsn = parseDsn(line);
+    if (dsn) this.lastEnhancedStatus = dsnToString(dsn);
+    if (this.dualPhase === "idle" || this.dualPhase === "rcpt_real") {
+      if (isHighVolume(line)) {
+        this.finish(true, "high_volume");
+        return;
+      }
+      if (isOverQuota(line)) {
+        this.isCatchAllFlag = false;
+        this.finish(false, "over_quota");
+        return;
+      }
+      if (isInvalidMailboxError(line)) {
+        this.isCatchAllFlag = false;
+        this.finish(false, "not_found");
+        return;
+      }
     }
-    if (isInvalidMailboxError(line)) {
-      this.finish(false, "not_found");
+    if (MULTILINE_RE.test(line)) {
+      const step = this.steps[this.currentStepIndex];
+      if ((step === SMTPStep.ehlo || step === SMTPStep.helo) && line.startsWith("250-")) {
+        const upper = line.toUpperCase();
+        if (upper.includes("PIPELINING")) this.supportsPipelining = true;
+      }
       return;
     }
-    if (MULTILINE_RE.test(line)) return;
-    const code = line.slice(0, 3);
-    const numericCode = /^\d{3}$/.test(code) ? parseInt(code, 10) : null;
     if (numericCode === null) {
       this.finish(null, "unrecognized_response");
       return;
     }
-    this.dispatch(numericCode);
+    this.dispatch(numericCode, line);
   }
-  dispatch(code) {
+  dispatch(code, line) {
     const step = this.steps[this.currentStepIndex];
+    if (this.dualPhase !== "idle" && step === SMTPStep.rcptTo) {
+      this.handleEnvelopeReply(code, line);
+      return;
+    }
     switch (step) {
       case SMTPStep.greeting:
         if (code === 220) this.nextStep();
@@ -1326,11 +1402,91 @@ class SMTPProbeConnection {
         else this.finish(null, "mail_from_rejected");
         return;
       case SMTPStep.rcptTo:
-        if (code === 250 || code === 251) this.finish(true, "valid");
-        else if (code === 552 || code === 452) this.finish(false, "over_quota");
-        else if (code >= 400 && code < 500) this.finish(null, "temporary_failure");
-        else this.finish(null, "ambiguous");
+        this.handleEnvelopeReply(code, line);
+        return;
+    }
+  }
+  /**
+   * Dual-probe / pipelined-envelope reply router. Demuxes server replies for
+   * the three queued commands (real RCPT, probe RCPT, RSET) and resolves
+   * with the catch-all-aware verdict.
+   */
+  handleEnvelopeReply(code, line) {
+    if (this.dualPhase === "rcpt_real") {
+      this.realOutcome = classifyRcpt(code);
+      if (code === 552 || code === 452 || isOverQuota(line)) {
+        this.isCatchAllFlag = false;
+        if (this.dualPipelined) {
+          this.pendingDecision = { result: false, reason: "over_quota" };
+          this.dualPhase = "rcpt_probe";
+          return;
+        }
+        this.finish(false, "over_quota");
+        return;
+      }
+      if (this.realOutcome === "soft_reject") {
+        if (this.dualPipelined) {
+          this.pendingDecision = { result: null, reason: "temporary_failure" };
+          this.dualPhase = "rcpt_probe";
+          return;
+        }
+        this.finish(null, "temporary_failure");
+        return;
+      }
+      if (this.realOutcome === "hard_reject") {
+        const reason = isInvalidMailboxError(line) ? "not_found" : "ambiguous";
+        const result = reason === "not_found" ? false : null;
+        this.isCatchAllFlag = false;
+        if (this.dualPipelined) {
+          this.pendingDecision = { result, reason };
+          this.dualPhase = "rcpt_probe";
+          return;
+        }
+        this.finish(result, reason);
+        return;
+      }
+      if (this.dualPipelined) {
+        this.dualPhase = "rcpt_probe";
+      } else {
+        this.send(`RCPT TO:<${this.probeLocal}@${this.p.domain}>`);
+        this.dualPhase = "rcpt_probe";
+      }
+      return;
+    }
+    if (this.dualPhase === "rcpt_probe") {
+      this.probeOutcome = classifyRcpt(code);
+      if (this.dualPipelined) {
+        this.dualPhase = "rset";
+      } else {
+        this.send("RSET");
+        this.dualPhase = "rset";
+      }
+      return;
+    }
+    if (this.dualPhase === "rset") {
+      if (this.pendingDecision) {
+        this.finish(this.pendingDecision.result, this.pendingDecision.reason);
         return;
+      }
+      this.decideDualProbe();
+      return;
+    }
+  }
+  /** Final decision after both RCPT outcomes are known. Catch-all only when both 250. */
+  decideDualProbe() {
+    if (this.realOutcome === "accept" && this.probeOutcome === "accept") {
+      this.isCatchAllFlag = true;
+      this.finish(true, "valid");
+    } else if (this.realOutcome === "accept") {
+      this.isCatchAllFlag = false;
+      this.finish(true, "valid");
+    } else if (this.realOutcome === "hard_reject") {
+      this.isCatchAllFlag = false;
+      this.finish(false, "not_found");
+    } else if (this.realOutcome === "soft_reject") {
+      this.finish(null, "temporary_failure");
+    } else {
+      this.finish(null, "ambiguous");
     }
   }
   finish(result, reason) {
@@ -1349,9 +1505,22 @@ class SMTPProbeConnection {
     }
     const drain = setTimeout(() => this.socket?.destroy(), QUIT_DRAIN_MS);
     drain.unref?.();
-    this.resolveFn({ result, transcript: this.transcript, commands: this.commands });
+    this.resolveFn({
+      result,
+      reason,
+      ...this.lastEnhancedStatus !== void 0 ? { enhancedStatus: this.lastEnhancedStatus } : {},
+      ...this.lastResponseCode !== void 0 ? { responseCode: this.lastResponseCode } : {},
+      ...this.isCatchAllFlag !== void 0 ? { isCatchAll: this.isCatchAllFlag } : {},
+      transcript: this.transcript,
+      commands: this.commands
+    });
   }
 }
+function classifyRcpt(code) {
+  if (code === 250 || code === 251) return "accept";
+  if (code >= 400 && code < 500) return "soft_reject";
+  return "hard_reject";
+}
 
 class ArrayTranscriptCollector {
   constructor() {
@@ -2021,12 +2190,11 @@ async function verifyEmail(params) {
   const skipMx = (params.skipMxForDisposable ?? false) && result.isDisposable;
   const skipWhois = (params.skipDomainWhoisForDisposable ?? false) && result.isDisposable;
   await runWhoisChecks(domain, params, result, skipWhois, log, collector);
-  if ((params.verifyMx ?? true) || (params.verifySmtp ?? false)) {
-    if (skipMx) {
-      log(`[verifyEmail] skipping MX/SMTP for disposable: ${params.emailAddress}`);
-    } else {
-      await runMxAndSmtp(local, domain, params, result, log, collector);
-    }
+  const wantsMxOrSmtp = (params.verifyMx ?? true) || (params.verifySmtp ?? false);
+  if (wantsMxOrSmtp && skipMx) {
+    log(`[verifyEmail] skipping MX/SMTP for disposable: ${params.emailAddress}`);
+  } else if (wantsMxOrSmtp) {
+    await runMxAndSmtp(local, domain, params, result, log, collector);
   }
   result.metadata.verificationTime = Date.now() - startTime;
   if (captureTranscript) result.transcript = collector.steps;