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

package/dist/index.d.ts

@@ -5,22 +5,29 @@
  * (`isDisposableEmail`, `isFreeEmail`) live in their own modules so
  * `batch-verifier.ts` can pull `verifyEmail` directly without going through
  * this file. That broke a `index → batch-verifier → index` Rollup cycle.
+ *
+ * Anything `export`ed under `src/*.ts` should also be re-exported here so
+ * `import { … } from '@emailcheck/email-validator-js'` works for every
+ * public symbol. See the audit comment per-line below.
  */
 export * from './adapters/lru-adapter';
 export * from './adapters/redis-adapter';
 export { verifyEmailBatch } from './batch-verifier';
 export * from './cache';
 export * from './cache-interface';
-export { commonEmailDomains, defaultDomainSuggestionMethod, getDomainSimilarity, isCommonDomain, suggestDomain, suggestEmailDomain, } from './domain-suggester';
+export { commonEmailDomains, defaultDomainSuggestionMethod, defaultDomainSuggestionMethodAsync, getDomainSimilarity, isCommonDomain, suggestDomain, suggestEmailDomain, } from './domain-suggester';
 export { isValidEmail, isValidEmailDomain } from './email-validator';
 export { isDisposableEmail } from './is-disposable-email';
 export { isFreeEmail } from './is-free-email';
 export { isSpamEmail } from './is-spam-email';
 export { isSpamName } from './is-spam-name';
+export { resolveMxRecords } from './mx-resolver';
 export { cleanNameForAlgorithm, defaultNameDetectionMethod, detectName, detectNameForAlgorithm, detectNameFromEmail, } from './name-detector';
 export { refineReasonByEnhancedStatus } from './refine-reason';
 export { type ParsedSmtpError, parseSmtpError } from './smtp-error-parser';
+export { type ParsedDsn, parseDsn, verifyMailboxSMTP } from './smtp-verifier';
 export { ArrayTranscriptCollector, NULL_COLLECTOR, type TranscriptCollector, } from './transcript';
 export * from './types';
 export { domainPorts, verifyEmail } from './verify-email';
 export { getDomainAge, getDomainRegistrationStatus } from './whois';
+export { type ParsedWhoisResult, parseWhoisData } from './whois-parser';

package/dist/index.esm.js

@@ -992,19 +992,25 @@ function defaultProbeLocal() {
   return `${randomBytes(8).toString("hex")}-noexist`;
 }
 async function verifyMailboxSMTP(params) {
-  var _a, _b, _c, _d, _e, _f, _g, _h, _j;
+  var _a, _b, _c, _d, _e, _f, _g, _h, _j, _k, _l, _m, _o, _p, _q;
   const { local, domain, options = {} } = params;
   const mxRecords = (_a = params.mxRecords) !== null && _a !== void 0 ? _a : [];
   const ports = ((_b = options.ports) !== null && _b !== void 0 ? _b : DEFAULT_PORTS).filter((port) => Number.isInteger(port) && port > 0 && port < 65536);
-  const timeout = (_c = options.timeout) !== null && _c !== void 0 ? _c : DEFAULT_TIMEOUT_MS;
-  const tlsConfig = (_d = options.tls) !== null && _d !== void 0 ? _d : true;
-  const hostname = (_e = options.hostname) !== null && _e !== void 0 ? _e : "localhost";
+  const perAttemptTimeoutMs = (_c = options.perAttemptTimeoutMs) !== null && _c !== void 0 ? _c : DEFAULT_TIMEOUT_MS;
+  const tlsConfig = (_d = options.tlsConfig) !== null && _d !== void 0 ? _d : true;
+  const heloHostname = (_e = options.heloHostname) !== null && _e !== void 0 ? _e : "localhost";
   const debug = (_f = options.debug) !== null && _f !== void 0 ? _f : false;
   const captureTranscript = (_g = options.captureTranscript) !== null && _g !== void 0 ? _g : false;
   const sequence = options.sequence;
   const cache = options.cache;
   const log = debug ? (...args) => console.log("[SMTP]", ...args) : () => {
   };
+  const totalDeadlineMs = options.totalDeadlineMs;
+  const maxConsecutiveFailures = options.maxConsecutiveFailures;
+  const maxMxHosts = options.maxMxHosts;
+  const retryAttempts = (_j = (_h = options.retry) === null || _h === void 0 ? void 0 : _h.attempts) !== null && _j !== void 0 ? _j : 0;
+  const retryDelayMs = (_l = (_k = options.retry) === null || _k === void 0 ? void 0 : _k.delayMs) !== null && _l !== void 0 ? _l : 200;
+  const retryBackoff = (_o = (_m = options.retry) === null || _m === void 0 ? void 0 : _m.backoff) !== null && _o !== void 0 ? _o : "exponential";
   const startedAtMs = Date.now();
   const primaryMx = mxRecords[0];
   if (!primaryMx) {
@@ -1018,14 +1024,14 @@ async function verifyMailboxSMTP(params) {
   const probeOptions = {
     local,
     domain,
-    timeout,
+    perAttemptTimeoutMs,
     tlsConfig,
-    hostname,
+    heloHostname,
     sequence,
     log,
     catchAllProbeLocal: options.catchAllProbeLocal,
-    pipelining: (_h = options.pipelining) !== null && _h !== void 0 ? _h : "auto",
-    startTls: (_j = options.startTls) !== null && _j !== void 0 ? _j : "auto"
+    pipelining: (_p = options.pipelining) !== null && _p !== void 0 ? _p : "auto",
+    startTls: (_q = options.startTls) !== null && _q !== void 0 ? _q : "auto"
   };
   const verdictCache = cache ? getCacheStore(cache, "smtp") : null;
   const verdictKey = `${primaryMx}:${local}@${domain}`;
@@ -1041,17 +1047,42 @@ async function verifyMailboxSMTP(params) {
   const mxHostsTried = [];
   let mxAttempts = 0;
   let portAttempts = 0;
+  let consecutiveFailures = 0;
   let lastReason = "all_attempts_failed";
   let lastEnhancedStatus;
   let lastResponseCode;
-  for (const mxHost of mxRecords) {
+  let stoppedEarly = null;
+  const isConnectionFailure = (reason) => reason === "connection_error" || reason === "connection_timeout" || reason === "connection_closed" || reason === "socket_timeout";
+  const retryDelayFor = (attemptIndex) => retryBackoff === "exponential" ? retryDelayMs * 2 ** (attemptIndex - 1) : retryDelayMs;
+  const probeWithRetry = async (mxHost, port) => {
+    let lastProbe = await runProbe({ ...probeOptions, mxHost, port });
+    for (let i = 1; i <= retryAttempts; i++) {
+      if (lastProbe.result !== null || !isConnectionFailure(lastProbe.reason))
+        break;
+      const delay = retryDelayFor(i);
+      log(`retry ${i}/${retryAttempts} on ${mxHost}:${port} after ${delay}ms (last: ${lastProbe.reason})`);
+      await new Promise((r) => setTimeout(r, delay));
+      portAttempts++;
+      lastProbe = await runProbe({ ...probeOptions, mxHost, port });
+    }
+    return lastProbe;
+  };
+  outer: for (const mxHost of mxRecords) {
+    if (maxMxHosts !== void 0 && mxAttempts >= maxMxHosts) {
+      stoppedEarly = "max_mx_hosts";
+      break;
+    }
     mxHostsTried.push(mxHost);
     mxAttempts++;
     const portsForThisMx = mxHost === primaryMx && cachedPort ? [cachedPort, ...ports.filter((p) => p !== cachedPort)] : ports;
     for (const port of portsForThisMx) {
+      if (totalDeadlineMs !== void 0 && Date.now() - startedAtMs >= totalDeadlineMs) {
+        stoppedEarly = "deadline";
+        break outer;
+      }
       portAttempts++;
       log(`Testing ${mxHost}:${port}`);
-      const probe = await runProbe({ ...probeOptions, mxHost, port });
+      const probe = await probeWithRetry(mxHost, port);
       collectTranscript(transcript, commands, probe, mxHost, port);
       lastReason = probe.reason;
       if (probe.enhancedStatus !== void 0)
@@ -1070,8 +1101,15 @@ async function verifyMailboxSMTP(params) {
           await safeCacheSet(portCache, primaryMx, port);
         return { smtpResult: smtpResult2, cached: false, port, portCached: cachedPort === port };
       }
+      consecutiveFailures = isConnectionFailure(probe.reason) ? consecutiveFailures + 1 : 0;
+      if (maxConsecutiveFailures !== void 0 && consecutiveFailures >= maxConsecutiveFailures) {
+        stoppedEarly = "consecutive_failures";
+        break outer;
+      }
     }
   }
+  if (stoppedEarly)
+    log(`Stopped early: ${stoppedEarly}`);
   log(`All MX\xD7port attempts failed (mx=${mxAttempts}, port=${portAttempts})`);
   const metrics = makeMetrics(mxHostsTried, mxAttempts, portAttempts, void 0, startedAtMs);
   const smtpResult = {
@@ -1218,17 +1256,17 @@ class SMTPProbeConnection {
     } else {
       this.socket = net$1.connect({ host: this.p.mxHost, port: this.p.port }, onConnect);
     }
-    this.socket.setTimeout(this.p.timeout, () => this.finish(null, "socket_timeout"));
+    this.socket.setTimeout(this.p.perAttemptTimeoutMs, () => this.finish(null, "socket_timeout"));
     this.socket.on("error", () => this.finish(null, "connection_error"));
     this.socket.on("close", () => this.finish(null, "connection_closed"));
   }
   armConnectionTimer() {
-    this.connectionTimer = setTimeout(() => this.finish(null, "connection_timeout"), this.p.timeout);
+    this.connectionTimer = setTimeout(() => this.finish(null, "connection_timeout"), this.p.perAttemptTimeoutMs);
   }
   resetStepTimer() {
     if (this.stepTimer)
       clearTimeout(this.stepTimer);
-    this.stepTimer = setTimeout(() => this.finish(null, "step_timeout"), this.p.timeout);
+    this.stepTimer = setTimeout(() => this.finish(null, "step_timeout"), this.p.perAttemptTimeoutMs);
   }
   send(cmd) {
     var _a;
@@ -1257,10 +1295,10 @@ class SMTPProbeConnection {
         return;
       // server-driven; nothing to send
       case SMTPStep.ehlo:
-        this.send(`EHLO ${this.p.hostname}`);
+        this.send(`EHLO ${this.p.heloHostname}`);
         return;
       case SMTPStep.helo:
-        this.send(`HELO ${this.p.hostname}`);
+        this.send(`HELO ${this.p.heloHostname}`);
         return;
       case SMTPStep.startTls:
         this.executeStartTls();
@@ -1332,7 +1370,7 @@ class SMTPProbeConnection {
       this.supportsStartTls = false;
       this.supportsPipelining = false;
       this.postUpgradeReEhlo = true;
-      this.send(`EHLO ${this.p.hostname}`);
+      this.send(`EHLO ${this.p.heloHostname}`);
     });
     this.socket = tlsSocket;
     this.socket.on("data", this.onData);
@@ -1340,7 +1378,7 @@ class SMTPProbeConnection {
       this.finish(null, this.tlsUpgrading ? "tls_handshake_failed" : "connection_error");
     });
     this.socket.on("close", () => this.finish(null, "connection_closed"));
-    this.socket.setTimeout(this.p.timeout, () => this.finish(null, "socket_timeout"));
+    this.socket.setTimeout(this.p.perAttemptTimeoutMs, () => this.finish(null, "socket_timeout"));
   }
   /**
    * Send the dual-probe envelope (real RCPT + probe RCPT + RSET). Pipelined
@@ -2309,11 +2347,11 @@ async function runWhoisChecks(domain, params, result, skipWhois, log, collector)
     log(`[verifyEmail] WHOIS checks skipped for disposable: ${domain}`);
     return;
   }
-  const whoisTimeout = (_a = params.whoisTimeout) !== null && _a !== void 0 ? _a : 5e3;
+  const whoisTimeoutMs = (_a = params.whoisTimeoutMs) !== null && _a !== void 0 ? _a : 5e3;
   const debug = (_b = params.debug) !== null && _b !== void 0 ? _b : false;
   if (params.checkDomainAge) {
     try {
-      result.domainAge = await collector.record("whois-age", () => getDomainAge(domain, whoisTimeout, debug, params.cache), (info) => {
+      result.domainAge = await collector.record("whois-age", () => getDomainAge(domain, whoisTimeoutMs, debug, params.cache), (info) => {
         var _a2, _b2, _c2, _d2, _e, _f;
         return {
           domain,
@@ -2332,7 +2370,7 @@ async function runWhoisChecks(domain, params, result, skipWhois, log, collector)
   }
   if (params.checkDomainRegistration) {
     try {
-      result.domainRegistration = await collector.record("whois-registration", () => getDomainRegistrationStatus(domain, whoisTimeout, debug, params.cache), (info) => {
+      result.domainRegistration = await collector.record("whois-registration", () => getDomainRegistrationStatus(domain, whoisTimeoutMs, debug, params.cache), (info) => {
         var _a2, _b2, _c2, _d2, _e, _f;
         return {
           domain,
@@ -2403,7 +2441,11 @@ async function runSmtp(local, domain, mxRecords, params, result, log, collector)
         options: {
           cache: params.cache,
           ports: resolveSmtpPorts(params.smtpPort, mxRecords[0]),
-          timeout: (_a = params.timeout) !== null && _a !== void 0 ? _a : 4e3,
+          perAttemptTimeoutMs: (_a = params.smtpPerAttemptTimeoutMs) !== null && _a !== void 0 ? _a : 4e3,
+          totalDeadlineMs: params.smtpTotalDeadlineMs,
+          maxConsecutiveFailures: params.smtpMaxConsecutiveFailures,
+          maxMxHosts: params.smtpMaxMxHosts,
+          retry: params.smtpRetry,
           debug: (_b = params.debug) !== null && _b !== void 0 ? _b : false,
           // Forward transcript capture so the SMTP step's details include
           // the full per-port transcript when the caller asked for it.
@@ -2444,7 +2486,7 @@ function smtpVerdictFor(validSmtp) {
 }
 
 async function verifyEmailBatch(params) {
-  const { emailAddresses, concurrency = 5, timeout = 4e3, verifyMx = true, verifySmtp = false, checkDisposable = true, checkFree = true, detectName = false, nameDetectionMethod, suggestDomain = false, domainSuggestionMethod, commonDomains, skipMxForDisposable = false, skipDomainWhoisForDisposable = false, cache } = params;
+  const { emailAddresses, concurrency = 5, smtpPerAttemptTimeoutMs = 4e3, smtpTotalDeadlineMs, smtpMaxConsecutiveFailures, smtpMaxMxHosts, smtpRetry, verifyMx = true, verifySmtp = false, checkDisposable = true, checkFree = true, detectName = false, nameDetectionMethod, suggestDomain = false, domainSuggestionMethod, commonDomains, skipMxForDisposable = false, skipDomainWhoisForDisposable = false, cache } = params;
   const startTime = Date.now();
   const results = /* @__PURE__ */ new Map();
   const batches = [];
@@ -2459,7 +2501,11 @@ async function verifyEmailBatch(params) {
       try {
         const result = await verifyEmail({
           emailAddress: email,
-          timeout,
+          smtpPerAttemptTimeoutMs,
+          smtpTotalDeadlineMs,
+          smtpMaxConsecutiveFailures,
+          smtpMaxMxHosts,
+          smtpRetry,
           verifyMx,
           verifySmtp,
           checkDisposable,
@@ -2750,5 +2796,5 @@ function parseSmtpError(errorMessage) {
   return { isDisabled, hasFullInbox, isCatchAll, isInvalid };
 }
 
-export { ArrayTranscriptCollector, DEFAULT_CACHE_OPTIONS, EmailProvider, LRUAdapter, NULL_COLLECTOR, RedisAdapter, SMTPStep, VerificationErrorCode, cleanNameForAlgorithm, clearDefaultCache, commonEmailDomains, defaultDomainSuggestionMethod, defaultNameDetectionMethod, detectName, detectNameForAlgorithm, detectNameFromEmail, domainPorts, getCacheStore, getDefaultCache, getDomainAge, getDomainRegistrationStatus, getDomainSimilarity, isCommonDomain, isDisposableEmail, isFreeEmail, isSpamEmail, isSpamName, isValidEmail, isValidEmailDomain, parseSmtpError, refineReasonByEnhancedStatus, suggestDomain, suggestEmailDomain, verifyEmail, verifyEmailBatch };
+export { ArrayTranscriptCollector, DEFAULT_CACHE_OPTIONS, EmailProvider, LRUAdapter, NULL_COLLECTOR, RedisAdapter, SMTPStep, VerificationErrorCode, cleanNameForAlgorithm, clearDefaultCache, commonEmailDomains, defaultDomainSuggestionMethod, defaultDomainSuggestionMethodAsync, defaultNameDetectionMethod, detectName, detectNameForAlgorithm, detectNameFromEmail, domainPorts, getCacheStore, getDefaultCache, getDomainAge, getDomainRegistrationStatus, getDomainSimilarity, isCommonDomain, isDisposableEmail, isFreeEmail, isSpamEmail, isSpamName, isValidEmail, isValidEmailDomain, parseDsn, parseSmtpError, parseWhoisData, refineReasonByEnhancedStatus, resolveMxRecords, suggestDomain, suggestEmailDomain, verifyEmail, verifyEmailBatch, verifyMailboxSMTP };
 //# sourceMappingURL=index.esm.js.map