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

package/README.md

@@ -129,79 +129,57 @@ const result = await verifyEmail({
   timeout: 3000
 });
 
-console.log(result.validFormat); // true
-console.log(result.validMx);     // true
-console.log(result.validSmtp);   // 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<IVerifyEmailResult>`
+#### `verifyEmail(params: IVerifyEmailParams): Promise<VerificationResult>`
 
-Basic email verification with backward compatibility.
+Comprehensive email verification with detailed results and error codes.
 
 **Parameters:**
 - `emailAddress` (string, required): Email address to verify
 - `timeout` (number): Timeout in milliseconds (default: 4000)
-- `verifyMx` (boolean): Check MX records (default: false)
+- `verifyMx` (boolean): Check MX records (default: true)
 - `verifySmtp` (boolean): Verify SMTP connection (default: false)
 - `smtpPort` (number): Custom SMTP port
 - `debug` (boolean): Enable debug logging (default: false)
+- `checkDisposable` (boolean): Check for disposable emails (default: true)
+- `checkFree` (boolean): Check for free email providers (default: true)
+- `retryAttempts` (number): Retry attempts for failures (default: 1)
 - `detectName` (boolean): Detect names from email address (default: false)
 - `nameDetectionMethod` (function): Custom name detection method
-- `suggestDomain` (boolean): Enable domain typo suggestions (default: false)
+- `suggestDomain` (boolean): Enable domain typo suggestions (default: true)
 - `domainSuggestionMethod` (function): Custom domain suggestion method
 - `commonDomains` (string[]): Custom list of domains for suggestions
+- `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
 {
+  email: string;
   validFormat: boolean;
   validMx: boolean | null;
   validSmtp: boolean | null;
+  isDisposable: boolean;
+  isFree: boolean;
   detectedName?: DetectedName | null;
-  domainSuggestion?: DomainSuggestion | null;
-}
-```
-
-#### `verifyEmailDetailed(params: IVerifyEmailParams): Promise<DetailedVerificationResult>`
-
-Advanced verification with detailed results and error codes.
-
-**Additional Parameters:**
-- `checkDisposable` (boolean): Check for disposable emails (default: true)
-- `checkFree` (boolean): Check for free email providers (default: true)
-- `retryAttempts` (number): Retry attempts for failures (default: 1)
-- `detectName` (boolean): Detect names from email address (default: false)
-- `suggestDomain` (boolean): Enable domain typo suggestions (default: true in detailed mode)
-
-**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;
-  detectedName?: DetectedName | null;
+  domainAge?: DomainAgeInfo | null;
+  domainRegistration?: DomainRegistrationInfo | null;
   domainSuggestion?: DomainSuggestion | null;
   metadata?: {
     verificationTime: number;
     cached: boolean;
+    error?: VerificationErrorCode;
   };
 }
 ```
@@ -213,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`
@@ -221,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;
@@ -591,32 +568,33 @@ Number of retry attempts for transient failures. Default: `1`.
 ```typescript
 import { verifyEmail } from '@emailcheck/email-validator-js';
 
-const { validFormat, validSmtp, validMx } = await verifyEmail({ 
-  emailAddress: 'foo@email.com', 
-  verifyMx: true, 
-  verifySmtp: true, 
-  timeout: 3000 
+const result = await verifyEmail({
+  emailAddress: 'foo@email.com',
+  verifyMx: true,
+  verifySmtp: true,
+  timeout: 3000
 });
-// validFormat: true
-// validMx: true
-// validSmtp: true
+console.log(result.validFormat);  // true
+console.log(result.validMx);      // true
+console.log(result.validSmtp);    // true
 ```
 
 ### Detailed Verification (NEW)
 ```typescript
-import { verifyEmailDetailed } from '@emailcheck/email-validator-js';
+import { verifyEmail } from '@emailcheck/email-validator-js';
 
-const result = await verifyEmailDetailed({
+const result = await verifyEmail({
   emailAddress: 'foo@email.com',
   verifyMx: true,
   verifySmtp: true,
   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
 ```
 
@@ -630,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
@@ -639,7 +618,7 @@ const result = await verifyEmailBatch({
 
 ### Name Detection (ENHANCED)
 ```typescript
-import { detectName, verifyEmailDetailed } from '@emailcheck/email-validator-js';
+import { detectName, verifyEmail } from '@emailcheck/email-validator-js';
 
 // Standalone name detection - now with composite name support
 const name = detectName('john.doe@mydomain.com');
@@ -657,7 +636,7 @@ const withSuffix = detectName('jane.smith.dev@mydomain.com');
 // withSuffix: { firstName: 'Jane', lastName: 'Smith', confidence: 0.7 }
 
 // Integrated with email verification
-const result = await verifyEmailDetailed({
+const result = await verifyEmail({
   emailAddress: 'jane_smith@mydomain.com',
   detectName: true
 });
@@ -678,14 +657,14 @@ const resultCustom = await verifyEmail({
 
 ### Domain Typo Detection (NEW)
 ```typescript
-import { suggestEmailDomain, verifyEmailDetailed } from '@emailcheck/email-validator-js';
+import { suggestEmailDomain, verifyEmail } from '@emailcheck/email-validator-js';
 
 // Standalone domain suggestion
 const suggestion = suggestEmailDomain('user@gmial.com');
 // suggestion: { original: 'user@gmial.com', suggested: 'user@gmail.com', confidence: 0.95 }
 
 // Integrated with email verification (enabled by default in detailed mode)
-const result = await verifyEmailDetailed({
+const result = await verifyEmail({
   emailAddress: 'john@yaho.com',
   suggestDomain: true  // Default: true for detailed verification
 });
@@ -705,20 +684,20 @@ const resultCustom = await verifyEmail({
 
 When a domain does not exist or has no MX records:
 ```typescript
-const result = await verifyEmail({ 
-  emailAddress: 'foo@bad-domain.com', 
-  verifyMx: true, 
-  verifySmtp: true 
+const result = await verifyEmail({
+  emailAddress: 'foo@bad-domain.com',
+  verifyMx: true,
+  verifySmtp: true
 });
-// validFormat: true
-// validMx: false
-// validSmtp: 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 verifyEmailDetailed({
+const result = await verifyEmail({
   emailAddress: 'user@suspicious-domain.com',
   verifyMx: true,
   verifySmtp: true,
@@ -726,8 +705,14 @@ const detailed = await verifyEmailDetailed({
   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;
@@ -767,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);
   }
 }
@@ -907,7 +892,7 @@ const customCache = CacheFactory.createCustomCache(
 );
 
 // Use with verification
-const result = await verifyEmailDetailed({
+const result = await verifyEmail({
   emailAddress: 'user@mydomain.com',
   verifyMx: true,
   verifySmtp: true,
@@ -1058,7 +1043,7 @@ process.on('SIGTERM', async () => {
 });
 ```
 
-**Note:** Yahoo, Hotmail, and some providers always return `validSmtp: 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, type IVerifyEmailResult } 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';
@@ -11,10 +11,6 @@ export declare function isDisposableEmail(emailOrDomain: string, cache?: ICache
 export declare function isFreeEmail(emailOrDomain: string, cache?: ICache | null): Promise<boolean>;
 export declare const domainPorts: Record<string, number>;
 /**
- * Verify email address with basic result format (backward compatible)
+ * Verify email address
  */
-export declare function verifyEmail(params: IVerifyEmailParams): Promise<IVerifyEmailResult>;
-/**
- * Verify email address with detailed result format
- */
-export declare function verifyEmailDetailed(params: IVerifyEmailParams): Promise<DetailedVerificationResult>;
+export declare function verifyEmail(params: IVerifyEmailParams): Promise<VerificationResult>;