@emailcheck/email-validator-js 2.13.1-beta.1 → 2.13.1-beta.2

package/README.md

@@ -129,17 +129,16 @@ const result = await verifyEmail({
   timeout: 3000
 });
 
-console.log(result.valid);     // Overall validity
-console.log(result.format.valid); // true
-console.log(result.domain.valid); // true or false
-console.log(result.smtp.valid);   // true or false
+console.log(result.validFormat);  // true
+console.log(result.validMx);      // true or false
+console.log(result.validSmtp);    // true or false
 ```
 
 ## API Reference
 
 ### Core Functions
 
-#### `verifyEmail(params: IVerifyEmailParams): Promise<DetailedVerificationResult>`
+#### `verifyEmail(params: IVerifyEmailParams): Promise<VerificationResult>`
 
 Comprehensive email verification with detailed results and error codes.
 
@@ -161,33 +160,26 @@ Comprehensive email verification with detailed results and error codes.
 - `checkDomainAge` (boolean): Check domain age (default: false)
 - `checkDomainRegistration` (boolean): Check domain registration status (default: false)
 - `whoisTimeout` (number): WHOIS lookup timeout (default: 5000)
+- `debug` (boolean): Enable debug logging including WHOIS lookups (default: false)
 - `cache` (ICache): Optional custom cache instance
 
 **Returns:**
 ```typescript
 {
-  valid: boolean;
   email: string;
-  format: {
-    valid: boolean;
-    error?: VerificationErrorCode;
-  };
-  domain: {
-    valid: boolean | null;
-    mxRecords?: string[];
-    error?: VerificationErrorCode;
-  };
-  smtp: {
-    valid: boolean | null;
-    error?: VerificationErrorCode;
-  };
-  disposable: boolean;
-  freeProvider: boolean;
+  validFormat: boolean;
+  validMx: boolean | null;
+  validSmtp: boolean | null;
+  isDisposable: boolean;
+  isFree: boolean;
   detectedName?: DetectedName | null;
+  domainAge?: DomainAgeInfo | null;
+  domainRegistration?: DomainRegistrationInfo | null;
   domainSuggestion?: DomainSuggestion | null;
   metadata?: {
     verificationTime: number;
     cached: boolean;
+    error?: VerificationErrorCode;
   };
 }
 ```
@@ -199,7 +191,6 @@ Verify multiple emails in parallel with concurrency control.
 **Parameters:**
 - `emailAddresses` (string[], required): Array of emails to verify
 - `concurrency` (number): Parallel processing limit (default: 5)
-- `detailed` (boolean): Return detailed results (default: false)
 - `detectName` (boolean): Detect names from email addresses
 - `suggestDomain` (boolean): Enable domain typo suggestions
 - Other parameters from `verifyEmail`
@@ -207,7 +198,7 @@ Verify multiple emails in parallel with concurrency control.
 **Returns:**
 ```typescript
 {
-  results: Map<string, DetailedVerificationResult | IVerifyEmailResult>;
+  results: Map<string, VerificationResult>;
   summary: {
     total: number;
     valid: number;
@@ -583,10 +574,9 @@ const result = await verifyEmail({
   verifySmtp: true,
   timeout: 3000
 });
-console.log(result.valid);       // true
-console.log(result.format.valid); // true
-console.log(result.domain.valid); // true
-console.log(result.smtp.valid);   // true
+console.log(result.validFormat);  // true
+console.log(result.validMx);      // true
+console.log(result.validSmtp);    // true
 ```
 
 ### Detailed Verification (NEW)
@@ -600,10 +590,11 @@ const result = await verifyEmail({
   checkDisposable: true,
   checkFree: true
 });
-// result.valid: true
-// result.disposable: false
-// result.freeProvider: false
-// result.domain.mxRecords: ['mx1.email.com', 'mx2.email.com']
+// result.validFormat: true
+// result.validMx: true
+// result.validSmtp: true
+// result.isDisposable: false
+// result.isFree: false
 // result.metadata.verificationTime: 125
 ```
 
@@ -617,7 +608,8 @@ const result = await verifyEmailBatch({
   emailAddresses: emails,
   concurrency: 5,
   verifyMx: true,
-  detailed: true
+  checkDisposable: true,
+  checkFree: true
 });
 // result.summary.valid: 2
 // result.summary.invalid: 1
@@ -697,16 +689,15 @@ const result = await verifyEmail({
   verifyMx: true,
   verifySmtp: true
 });
-// result.valid: false (domain or SMTP failed)
-// result.format.valid: true
-// result.domain.valid: false
-// result.smtp.valid: null (couldn't be performed)
+// result.validFormat: true (format is valid)
+// result.validMx: false (no MX records)
+// result.validSmtp: null (couldn't be performed)
 ```
 
 ### Using Detailed Verification for Better Insights
 
 ```typescript
-const detailed = await verifyEmail({
+const result = await verifyEmail({
   emailAddress: 'user@suspicious-domain.com',
   verifyMx: true,
   verifySmtp: true,
@@ -714,8 +705,14 @@ const detailed = await verifyEmail({
   checkFree: true
 });
 
-if (!detailed.valid) {
-  switch (detailed.domain.error) {
+if (!result.validFormat) {
+  console.log('Invalid email format');
+} else if (!result.validMx) {
+  console.log('Invalid domain - no MX records');
+} else if (result.isDisposable) {
+  console.log('Disposable email detected');
+} else if (result.metadata?.error) {
+  switch (result.metadata.error) {
     case VerificationErrorCode.DISPOSABLE_EMAIL:
       console.log('Rejected: Disposable email');
       break;
@@ -755,7 +752,7 @@ console.log(`Time: ${batch.summary.processingTime}ms`);
 // Filter out invalid emails
 const validEmails = [];
 for (const [email, result] of batch.results) {
-  if (result.valid) {
+  if (result.validFormat) {
     validEmails.push(email);
   }
 }
@@ -1046,7 +1043,7 @@ process.on('SIGTERM', async () => {
 });
 ```
 
-**Note:** Yahoo, Hotmail, and some providers always return `result.smtp.valid: true` as they don't allow mailbox verification.
+**Note:** Yahoo, Hotmail, and some providers always return `result.validSmtp: true` as they don't allow mailbox verification.
 
 ## 🌐 Serverless Deployment
 

package/dist/index.d.ts

@@ -1,5 +1,5 @@
 import type { ICache } from './cache-interface';
-import { type DetailedVerificationResult, type IVerifyEmailParams } from './types';
+import { type IVerifyEmailParams, type VerificationResult } from './types';
 export { verifyEmailBatch } from './batch';
 export { clearAllCaches } from './cache';
 export { COMMON_EMAIL_DOMAINS, defaultDomainSuggestionMethod, getDomainSimilarity, isCommonDomain, suggestDomain, suggestEmailDomain, } from './domain-suggester';
@@ -13,4 +13,4 @@ export declare const domainPorts: Record<string, number>;
 /**
  * Verify email address
  */
-export declare function verifyEmail(params: IVerifyEmailParams): Promise<DetailedVerificationResult>;
+export declare function verifyEmail(params: IVerifyEmailParams): Promise<VerificationResult>;

package/dist/index.esm.js

@@ -1732,37 +1732,50 @@ const WHOIS_SERVERS = {
   ar: "whois.nic.ar",
   cl: "whois.nic.cl"
 };
-function queryWhoisServer(domain, server, timeout = 5e3) {
+function queryWhoisServer(domain, server, timeout = 5e3, debug = false) {
+  const log = debug ? console.debug : (..._args) => {
+  };
   return new Promise((resolve, reject) => {
     const client = new net.Socket();
     let data = "";
+    log(`[whois] querying ${server} for domain ${domain}`);
     const timer = setTimeout(() => {
+      log(`[whois] timeout after ${timeout}ms for ${domain} at ${server}`);
       client.destroy();
       reject(new Error("WHOIS query timeout"));
     }, timeout);
     client.connect(43, server, () => {
+      log(`[whois] connected to ${server}, sending query for ${domain}`);
       client.write(`${domain}\r
 `);
     });
     client.on("data", (chunk) => {
-      data += chunk.toString();
+      const chunkStr = chunk.toString();
+      data += chunkStr;
+      log(`[whois] received ${chunkStr.length} bytes from ${server}`);
     });
     client.on("close", () => {
       clearTimeout(timer);
+      log(`[whois] connection closed, received total ${data.length} bytes from ${server}`);
       resolve(data);
     });
     client.on("error", (err) => {
       clearTimeout(timer);
+      log(`[whois] error querying ${server}: ${err.message}`);
       reject(err);
     });
   });
 }
-async function getWhoisData(domain, timeout = 5e3) {
+async function getWhoisData(domain, timeout = 5e3, debug = false) {
   var _a;
+  const log = debug ? console.debug : (..._args) => {
+  };
   const cacheKey = `whois:${domain}`;
   const cache = whoisCacheStore();
+  log(`[whois] getting WHOIS data for ${domain}`);
   const cached = await cache.get(cacheKey);
   if (cached !== null && cached !== void 0) {
+    log(`[whois] using cached data for ${domain}`);
     return cached;
   }
   try {
@@ -1770,41 +1783,55 @@ async function getWhoisData(domain, timeout = 5e3) {
     if (!tld) {
       throw new Error("Invalid domain");
     }
+    log(`[whois] extracted TLD: ${tld} for domain: ${domain}`);
     const whoisServer = WHOIS_SERVERS[tld];
     if (!whoisServer) {
+      log(`[whois] no specific server for TLD ${tld}, trying IANA`);
       const defaultServer = "whois.iana.org";
-      const ianaResponse = await queryWhoisServer(domain, defaultServer, timeout);
+      const ianaResponse = await queryWhoisServer(domain, defaultServer, timeout, debug);
       const referMatch = ianaResponse.match(/refer:\s+(\S+)/i);
       if (referMatch === null || referMatch === void 0 ? void 0 : referMatch[1]) {
         const referredServer = referMatch[1];
-        const whoisResponse2 = await queryWhoisServer(domain, referredServer, timeout);
+        log(`[whois] IANA referred to ${referredServer} for ${domain}`);
+        const whoisResponse2 = await queryWhoisServer(domain, referredServer, timeout, debug);
         const whoisData3 = parseWhoisData({ rawData: whoisResponse2, domain });
         await cache.set(cacheKey, whoisData3);
+        log(`[whois] successfully retrieved and cached WHOIS data from referred server for ${domain}`);
         return whoisData3;
       }
       const whoisData2 = parseWhoisData({ rawData: ianaResponse, domain });
       await cache.set(cacheKey, whoisData2);
+      log(`[whois] successfully retrieved and cached WHOIS data from IANA for ${domain}`);
       return whoisData2;
     }
-    const whoisResponse = await queryWhoisServer(domain, whoisServer, timeout);
+    log(`[whois] using WHOIS server ${whoisServer} for TLD ${tld}`);
+    const whoisResponse = await queryWhoisServer(domain, whoisServer, timeout, debug);
     const whoisData = parseWhoisData({ rawData: whoisResponse, domain });
     await cache.set(cacheKey, whoisData);
+    log(`[whois] successfully retrieved and cached WHOIS data for ${domain}`);
     return whoisData;
   } catch (_error) {
+    log(`[whois] failed to get WHOIS data for ${domain}: ${_error instanceof Error ? _error.message : "Unknown error"}`);
     return null;
   }
 }
-async function getDomainAge(domain, timeout = 5e3) {
+async function getDomainAge(domain, timeout = 5e3, debug = false) {
+  const log = debug ? console.debug : (..._args) => {
+  };
   try {
     const cleanDomain = domain.replace(/^https?:\/\//, "").split("/")[0].split("@").pop();
     if (!cleanDomain) {
+      log(`[whois] invalid domain format: ${domain}`);
       return null;
     }
+    log(`[whois] checking domain age for ${cleanDomain}`);
     if (!isValid(cleanDomain)) {
+      log(`[whois] domain validation failed: ${cleanDomain}`);
       return null;
     }
-    const whoisData = await getWhoisData(cleanDomain, timeout);
+    const whoisData = await getWhoisData(cleanDomain, timeout, debug);
     if (!whoisData || !whoisData.creationDate) {
+      log(`[whois] no creation date found for ${cleanDomain}`);
       return null;
     }
     const now = /* @__PURE__ */ new Date();
@@ -1812,6 +1839,7 @@ async function getDomainAge(domain, timeout = 5e3) {
     const ageInMilliseconds = now.getTime() - creationDate.getTime();
     const ageInDays = Math.floor(ageInMilliseconds / (1e3 * 60 * 60 * 24));
     const ageInYears = ageInDays / 365.25;
+    log(`[whois] calculated age for ${cleanDomain}: ${ageInDays} days (${ageInYears.toFixed(2)} years)`);
     return {
       domain: cleanDomain,
       creationDate,
@@ -1821,20 +1849,27 @@ async function getDomainAge(domain, timeout = 5e3) {
       updatedDate: whoisData.updatedDate ? new Date(whoisData.updatedDate) : null
     };
   } catch (_error) {
+    log(`[whois] error getting domain age for ${domain}: ${_error instanceof Error ? _error.message : "Unknown error"}`);
     return null;
   }
 }
-async function getDomainRegistrationStatus(domain, timeout = 5e3) {
+async function getDomainRegistrationStatus(domain, timeout = 5e3, debug = false) {
+  const log = debug ? console.debug : (..._args) => {
+  };
   try {
     const cleanDomain = domain.replace(/^https?:\/\//, "").split("/")[0].split("@").pop();
     if (!cleanDomain) {
+      log(`[whois] invalid domain format: ${domain}`);
       return null;
     }
+    log(`[whois] checking domain registration status for ${cleanDomain}`);
     if (!isValid(cleanDomain)) {
+      log(`[whois] domain validation failed: ${cleanDomain}`);
       return null;
     }
-    const whoisData = await getWhoisData(cleanDomain, timeout);
+    const whoisData = await getWhoisData(cleanDomain, timeout, debug);
     if (!whoisData || whoisData.isAvailable) {
+      log(`[whois] domain ${cleanDomain} is available or not registered`);
       return {
         domain: cleanDomain,
         isRegistered: false,
@@ -1862,6 +1897,7 @@ async function getDomainRegistrationStatus(domain, timeout = 5e3) {
       if (!isExpired) {
         daysUntilExpiration = Math.floor((expirationTime - currentTime) / (1e3 * 60 * 60 * 24));
       }
+      log(`[whois] domain ${cleanDomain} expires in ${daysUntilExpiration} days`);
     }
     const statusList = whoisData.status || [];
     const formattedStatusList = statusList.map((s) => {
@@ -1870,6 +1906,7 @@ async function getDomainRegistrationStatus(domain, timeout = 5e3) {
     });
     const isPendingDelete = formattedStatusList.some((s) => s.toLowerCase().includes("pendingdelete") || s.toLowerCase().includes("redemption"));
     const isLocked = formattedStatusList.some((s) => s.toLowerCase().includes("clienttransferprohibited") || s.toLowerCase().includes("servertransferprohibited"));
+    log(`[whois] domain ${cleanDomain} - registered: ${isRegistered}, expired: ${isExpired}, locked: ${isLocked}, pending delete: ${isPendingDelete}`);
     return {
       domain: cleanDomain,
       isRegistered,
@@ -1884,6 +1921,7 @@ async function getDomainRegistrationStatus(domain, timeout = 5e3) {
       isLocked
     };
   } catch (_error) {
+    log(`[whois] error getting domain registration status for ${domain}: ${_error instanceof Error ? _error.message : "Unknown error"}`);
     return null;
   }
 }
@@ -1916,7 +1954,7 @@ async function verifyEmailBatch(params) {
           commonDomains,
           cache
         });
-        if (result.valid) {
+        if (result.validFormat) {
           totalValid++;
         } else {
           totalInvalid++;
@@ -1926,7 +1964,7 @@ async function verifyEmailBatch(params) {
         totalErrors++;
         return {
           email,
-          result: createErrorDetailedResult(email)
+          result: createErrorResult(email)
         };
       }
     });
@@ -1946,18 +1984,18 @@ async function verifyEmailBatch(params) {
     }
   };
 }
-function createErrorDetailedResult(email, _error) {
+function createErrorResult(email, _error) {
   return {
-    valid: false,
     email,
-    format: { valid: false },
-    domain: { valid: null },
-    smtp: { valid: null },
-    disposable: false,
-    freeProvider: false,
+    validFormat: false,
+    validMx: null,
+    validSmtp: null,
+    isDisposable: false,
+    isFree: false,
     metadata: {
       verificationTime: 0,
-      cached: false
+      cached: false,
+      error: VerificationErrorCode.SMTP_CONNECTION_FAILED
     }
   };
 }
@@ -2027,26 +2065,25 @@ async function verifyEmail(params) {
   const log = debug ? console.debug : (..._args) => {
   };
   const result = {
-    valid: false,
     email: emailAddress,
-    format: { valid: false },
-    domain: { valid: null },
-    smtp: { valid: null },
-    disposable: false,
-    freeProvider: false,
+    validFormat: false,
+    validMx: null,
+    validSmtp: null,
+    isDisposable: false,
+    isFree: false,
     metadata: {
       verificationTime: 0,
       cached: false
     }
   };
   if (!isValidEmail(emailAddress)) {
-    result.format.error = VerificationErrorCode.INVALID_FORMAT;
     if (result.metadata) {
       result.metadata.verificationTime = Date.now() - startTime;
+      result.metadata.error = VerificationErrorCode.INVALID_FORMAT;
     }
     return result;
   }
-  result.format.valid = true;
+  result.validFormat = true;
   if (detectName2) {
     result.detectedName = detectNameFromEmail({
       email: emailAddress,
@@ -2056,64 +2093,67 @@ async function verifyEmail(params) {
   if (suggestDomain2) {
     const [, emailDomain] = emailAddress.split("@");
     if (emailDomain) {
-      result.domainSuggestion = domainSuggestionMethod ? domainSuggestionMethod(emailDomain) : await suggestEmailDomain(emailAddress, commonDomains);
+      const suggestion = domainSuggestionMethod ? domainSuggestionMethod(emailDomain) : await suggestEmailDomain(emailAddress, commonDomains);
+      if (suggestion) {
+        result.domainSuggestion = suggestion;
+      } else {
+        result.domainSuggestion = null;
+      }
     }
   }
   const [local, domain] = emailAddress.split("@");
   if (!domain || !local) {
-    result.format.error = VerificationErrorCode.INVALID_FORMAT;
     if (result.metadata) {
       result.metadata.verificationTime = Date.now() - startTime;
+      result.metadata.error = VerificationErrorCode.INVALID_FORMAT;
     }
     return result;
   }
   if (!await isValidEmailDomain(domain, params.cache)) {
-    result.domain.error = VerificationErrorCode.INVALID_DOMAIN;
     if (result.metadata) {
       result.metadata.verificationTime = Date.now() - startTime;
+      result.metadata.error = VerificationErrorCode.INVALID_DOMAIN;
     }
     return result;
   }
   if (checkDisposable) {
-    result.disposable = await isDisposableEmail(emailAddress, params.cache);
-    if (result.disposable) {
-      result.valid = false;
-      result.domain.error = VerificationErrorCode.DISPOSABLE_EMAIL;
+    result.isDisposable = await isDisposableEmail(emailAddress, params.cache);
+    if (result.isDisposable && result.metadata) {
+      result.metadata.error = VerificationErrorCode.DISPOSABLE_EMAIL;
     }
   }
   if (checkFree) {
-    result.freeProvider = await isFreeEmail(emailAddress, params.cache);
+    result.isFree = await isFreeEmail(emailAddress, params.cache);
   }
   if (checkDomainAge) {
     try {
-      result.domainAge = await getDomainAge(domain, whoisTimeout);
+      result.domainAge = await getDomainAge(domain, whoisTimeout, debug);
     } catch (err) {
-      log("[verifyEmailDetailed] Failed to get domain age", err);
+      log("[verifyEmail] Failed to get domain age", err);
       result.domainAge = null;
     }
   }
   if (checkDomainRegistration) {
     try {
-      result.domainRegistration = await getDomainRegistrationStatus(domain, whoisTimeout);
+      result.domainRegistration = await getDomainRegistrationStatus(domain, whoisTimeout, debug);
     } catch (err) {
-      log("[verifyEmailDetailed] Failed to get domain registration status", err);
+      log("[verifyEmail] Failed to get domain registration status", err);
       result.domainRegistration = null;
     }
   }
   if (verifyMx || verifySmtp) {
     try {
       const mxRecords = await resolveMxRecords(domain, params.cache);
-      result.domain.mxRecords = mxRecords;
-      result.domain.valid = mxRecords.length > 0;
-      if (!result.domain.valid) {
-        result.domain.error = VerificationErrorCode.NO_MX_RECORDS;
+      result.validMx = mxRecords.length > 0;
+      if (!result.validMx && result.metadata) {
+        result.metadata.error = VerificationErrorCode.NO_MX_RECORDS;
       }
       if (verifySmtp && mxRecords.length > 0) {
         const cacheKey = `${emailAddress}:smtp`;
         const smtpCacheInstance = smtpCacheStore(params.cache);
         const cachedSmtp = await smtpCacheInstance.get(cacheKey);
         if (cachedSmtp !== null && cachedSmtp !== void 0) {
-          result.smtp.valid = cachedSmtp;
+          result.validSmtp = cachedSmtp;
           if (result.metadata) {
             result.metadata.cached = true;
           }
@@ -2141,21 +2181,22 @@ async function verifyEmail(params) {
             retryAttempts: params.retryAttempts
           });
           await smtpCacheInstance.set(cacheKey, smtpResult);
-          result.smtp.valid = smtpResult;
+          result.validSmtp = smtpResult;
         }
-        if (result.smtp.valid === false) {
-          result.smtp.error = VerificationErrorCode.MAILBOX_NOT_FOUND;
-        } else if (result.smtp.valid === null) {
-          result.smtp.error = VerificationErrorCode.SMTP_CONNECTION_FAILED;
+        if (result.validSmtp === false && result.metadata) {
+          result.metadata.error = VerificationErrorCode.MAILBOX_NOT_FOUND;
+        } else if (result.validSmtp === null && result.metadata) {
+          result.metadata.error = VerificationErrorCode.SMTP_CONNECTION_FAILED;
         }
       }
     } catch (err) {
-      log("[verifyEmailDetailed] Failed to resolve MX records", err);
-      result.domain.valid = false;
-      result.domain.error = VerificationErrorCode.NO_MX_RECORDS;
+      log("[verifyEmail] Failed to resolve MX records", err);
+      result.validMx = false;
+      if (result.metadata) {
+        result.metadata.error = VerificationErrorCode.NO_MX_RECORDS;
+      }
     }
   }
-  result.valid = result.format.valid && result.domain.valid !== false && result.smtp.valid !== false && !result.disposable;
   if (result.metadata) {
     result.metadata.verificationTime = Date.now() - startTime;
   }