valid-email-checker 1.0.0

package/src/index.d.ts

@@ -0,0 +1,156 @@
+/**
+ * TypeScript Definitions for valid-email-checker
+ */
+
+export interface ValidationResult {
+  valid: boolean;
+  email: string;
+  normalized?: string | null;
+  local?: string | null;
+  domain?: string | null;
+  tld?: string;
+  errors?: string[];
+}
+
+export interface TemporaryEmailResult {
+  isTemporary: boolean;
+  email: string;
+  domain: string | null;
+  reason: string | null;
+  confidence: 'none' | 'low' | 'medium' | 'high';
+  matchType: string | null;
+}
+
+export interface SpamEmailResult {
+  isSpam: boolean;
+  email: string;
+  score: number;
+  maxScore: number;
+  spamLevel: 'none' | 'low' | 'medium' | 'high';
+  reasons: string[];
+  details: {
+    localPart: string | null;
+    domain: string | null;
+    matches: Array<{ type: string; pattern?: string; keyword?: string }>;
+  };
+}
+
+export interface MxResult {
+  hasMxRecords: boolean;
+  domain: string;
+  mxRecords: Array<{ exchange: string; priority: number; type?: string }>;
+  error: string | null;
+  fallbackToA?: boolean;
+}
+
+export interface FullValidationResult {
+  valid: boolean;
+  email: string;
+  normalized: string | null;
+  score: number;
+  quality: 'excellent' | 'good' | 'acceptable' | 'poor' | 'bad';
+  isTemporary: boolean;
+  isSpam: boolean;
+  details: {
+    format: ValidationResult | null;
+    temporary: TemporaryEmailResult | null;
+    spam: SpamEmailResult | null;
+    mx?: MxResult | { skipped: boolean; reason: string } | { error: string };
+  };
+  recommendations: string[];
+}
+
+export interface ValidationOptions {
+  strict?: boolean;
+  allowPlusAddressing?: boolean;
+  checkTld?: boolean;
+  maxLength?: number;
+  minLocalLength?: number;
+  maxLocalLength?: number;
+}
+
+export interface TempCheckOptions {
+  customDomains?: string[];
+  customPatterns?: RegExp[];
+  strictMode?: boolean;
+}
+
+export interface SpamCheckOptions {
+  customPatterns?: RegExp[];
+  threshold?: number;
+  strictMode?: boolean;
+}
+
+export interface FullValidationOptions {
+  checkFormat?: boolean;
+  checkTemporary?: boolean;
+  checkSpam?: boolean;
+  checkMx?: boolean;
+  spamThreshold?: number;
+  strictMode?: boolean;
+  mxTimeout?: number;
+}
+
+export interface EmailValidatorOptions {
+  allowPlusAddressing?: boolean;
+  checkMxRecords?: boolean;
+  strictMode?: boolean;
+  spamThreshold?: number;
+  customTempDomains?: string[];
+  customSpamPatterns?: RegExp[];
+  mxTimeout?: number;
+}
+
+// Main validation functions
+export function validateEmail(email: string, options?: ValidationOptions): ValidationResult;
+export function validateEmailAsync(email: string, options?: FullValidationOptions): Promise<FullValidationResult>;
+export function fullValidation(email: string, options?: FullValidationOptions): FullValidationResult;
+export function fullValidationAsync(email: string, options?: FullValidationOptions): Promise<FullValidationResult>;
+
+// Quick validators
+export function isValidEmail(email: string): boolean;
+export function isTempEmail(email: string): boolean;
+export function isTemporaryEmail(email: string, options?: TempCheckOptions): TemporaryEmailResult;
+export function isSpam(email: string, threshold?: number): boolean;
+export function isSpamEmail(email: string, options?: SpamCheckOptions): SpamEmailResult;
+
+// Utility functions
+export function normalizeEmail(email: string, options?: {
+  lowercase?: boolean;
+  removePlusAddressing?: boolean;
+  removeDotsFromGmail?: boolean;
+}): string | null;
+export function extractDomain(email: string): string | null;
+export function extractLocal(email: string): string | null;
+
+// Domain checks
+export function isDisposableDomain(domain: string): boolean;
+export function isSuspiciousDomain(domain: string): boolean;
+export function addDisposableDomains(domains: string[]): void;
+export function getDisposableDomainCount(): number;
+
+// MX validation
+export function checkMxRecords(domain: string, options?: { timeout?: number }): Promise<MxResult>;
+export function validateEmailMx(email: string, options?: { timeout?: number }): Promise<MxResult & { valid: boolean; email: string }>;
+export function batchCheckMxRecords(domains: string[], options?: { concurrency?: number; timeout?: number }): Promise<{ [domain: string]: MxResult }>;
+
+// Scoring
+export function getSpamScore(email: string): number;
+
+// EmailValidator class
+export class EmailValidator {
+  constructor(options?: EmailValidatorOptions);
+  validate(email: string): Promise<FullValidationResult>;
+  isValid(email: string): boolean;
+  isTemporary(email: string): boolean;
+  isSpam(email: string): boolean;
+  addTempDomains(domains: string[]): void;
+}
+
+// Constants
+export const DISPOSABLE_DOMAINS: Set<string>;
+export const EMAIL_REGEX: RegExp;
+export const SIMPLE_EMAIL_REGEX: RegExp;
+export const VALID_TLDS: Set<string>;
+export const SPAM_LOCAL_PATTERNS: RegExp[];
+export const SPAM_DOMAIN_PATTERNS: RegExp[];

package/src/index.js

@@ -0,0 +1,335 @@
+/**
+ * Valid Email Checker
+ * Comprehensive email validation library
+ * 
+ * Features:
+ * - Email format validation (RFC 5322)
+ * - Temporary/disposable email detection
+ * - Spam pattern detection
+ * - MX record verification
+ */
+
+const {
+  validateEmail,
+  isValidEmail,
+  normalizeEmail,
+  extractDomain,
+  extractLocal,
+  EMAIL_REGEX,
+  SIMPLE_EMAIL_REGEX,
+  VALID_TLDS
+} = require('./validators/formatValidator');
+
+const {
+  isTemporaryEmail,
+  isTempEmail,
+  isDisposableDomain,
+  addDisposableDomains,
+  getDisposableDomainCount
+} = require('./validators/tempMailDetector');
+
+const {
+  isSpamEmail,
+  isSpam,
+  getSpamScore,
+  isSuspiciousDomain,
+  SPAM_LOCAL_PATTERNS,
+  SPAM_DOMAIN_PATTERNS
+} = require('./validators/spamDetector');
+
+const {
+  checkMxRecords,
+  validateEmailMx,
+  batchCheckMxRecords
+} = require('./validators/mxValidator');
+
+const { DISPOSABLE_DOMAINS } = require('./data/disposableDomains');
+
+/**
+ * Perform full email validation combining all checks
+ * @param {string} email - Email to validate
+ * @param {object} options - Validation options
+ * @returns {object} Comprehensive validation result
+ */
+function fullValidation(email, options = {}) {
+  const {
+    checkFormat = true,
+    checkTemporary = true,
+    checkSpam = true,
+    spamThreshold = 30,
+    strictMode = false
+  } = options;
+
+  const result = {
+    valid: false,
+    email: email,
+    normalized: null,
+    score: 100,
+    isTemporary: false,
+    isSpam: false,
+    details: {
+      format: null,
+      temporary: null,
+      spam: null
+    },
+    recommendations: []
+  };
+
+  // Format validation
+  if (checkFormat) {
+    const formatResult = validateEmail(email, { strict: strictMode });
+    result.details.format = formatResult;
+    result.normalized = formatResult.normalized;
+    
+    if (!formatResult.valid) {
+      result.valid = false;
+      result.score = 0;
+      result.recommendations.push('Fix email format errors: ' + formatResult.errors.join(', '));
+      return result;
+    }
+  }
+
+  // Temporary email check
+  if (checkTemporary) {
+    const tempResult = isTemporaryEmail(email, { strictMode });
+    result.details.temporary = tempResult;
+    result.isTemporary = tempResult.isTemporary;
+    
+    if (tempResult.isTemporary) {
+      // Reduce score based on confidence
+      const scoreReduction = {
+        high: 50,
+        medium: 35,
+        low: 20
+      };
+      result.score -= scoreReduction[tempResult.confidence] || 30;
+      result.recommendations.push('Email appears to be from a disposable email service');
+    }
+  }
+
+  // Spam check
+  if (checkSpam) {
+    const spamResult = isSpamEmail(email, { threshold: spamThreshold, strictMode });
+    result.details.spam = spamResult;
+    result.isSpam = spamResult.isSpam;
+    
+    if (spamResult.score > 0) {
+      result.score -= Math.min(spamResult.score, 50);
+      if (spamResult.isSpam) {
+        result.recommendations.push('Email matches spam patterns: ' + spamResult.reasons.slice(0, 2).join(', '));
+      }
+    }
+  }
+
+  // Ensure score is within bounds
+  result.score = Math.max(0, Math.min(100, result.score));
+
+  // Determine overall validity
+  result.valid = result.score >= 50 && !result.isTemporary;
+
+  // Add quality assessment
+  if (result.score >= 90) {
+    result.quality = 'excellent';
+  } else if (result.score >= 70) {
+    result.quality = 'good';
+  } else if (result.score >= 50) {
+    result.quality = 'acceptable';
+  } else if (result.score >= 30) {
+    result.quality = 'poor';
+  } else {
+    result.quality = 'bad';
+  }
+
+  return result;
+}
+
+/**
+ * Async full validation with MX record check
+ * @param {string} email - Email to validate
+ * @param {object} options - Validation options
+ * @returns {Promise<object>} Comprehensive validation result
+ */
+async function fullValidationAsync(email, options = {}) {
+  const { checkMx = true, mxTimeout = 5000 } = options;
+
+  // Run sync validation first
+  const result = fullValidation(email, options);
+
+  // If format is invalid, skip MX check
+  if (!result.details.format?.valid) {
+    result.details.mx = { skipped: true, reason: 'Invalid format' };
+    return result;
+  }
+
+  // MX record validation
+  if (checkMx) {
+    try {
+      const mxResult = await validateEmailMx(email, { timeout: mxTimeout });
+      result.details.mx = mxResult;
+      
+      if (!mxResult.hasMxRecords) {
+        result.score -= 30;
+        result.recommendations.push('Domain does not have valid mail server records');
+      }
+    } catch (error) {
+      result.details.mx = { error: error.message };
+      result.score -= 10;
+    }
+  }
+
+  // Recalculate validity and quality
+  result.score = Math.max(0, Math.min(100, result.score));
+  result.valid = result.score >= 50 && !result.isTemporary;
+
+  if (result.score >= 90) {
+    result.quality = 'excellent';
+  } else if (result.score >= 70) {
+    result.quality = 'good';
+  } else if (result.score >= 50) {
+    result.quality = 'acceptable';
+  } else if (result.score >= 30) {
+    result.quality = 'poor';
+  } else {
+    result.quality = 'bad';
+  }
+
+  return result;
+}
+
+/**
+ * Validate email asynchronously (alias for convenience)
+ * @param {string} email - Email to validate
+ * @param {object} options - Options
+ * @returns {Promise<object>} Validation result
+ */
+async function validateEmailAsync(email, options = {}) {
+  return fullValidationAsync(email, options);
+}
+
+/**
+ * EmailValidator class for custom configuration
+ */
+class EmailValidator {
+  constructor(options = {}) {
+    this.options = {
+      allowPlusAddressing: true,
+      checkMxRecords: false,
+      strictMode: false,
+      spamThreshold: 30,
+      customTempDomains: [],
+      customSpamPatterns: [],
+      mxTimeout: 5000,
+      ...options
+    };
+
+    // Add custom temp domains
+    if (this.options.customTempDomains.length > 0) {
+      addDisposableDomains(this.options.customTempDomains);
+    }
+  }
+
+  /**
+   * Validate email
+   * @param {string} email - Email to validate
+   * @returns {Promise<object>|object} Validation result
+   */
+  async validate(email) {
+    const validationOptions = {
+      checkFormat: true,
+      checkTemporary: true,
+      checkSpam: true,
+      checkMx: this.options.checkMxRecords,
+      spamThreshold: this.options.spamThreshold,
+      strictMode: this.options.strictMode,
+      mxTimeout: this.options.mxTimeout,
+      customPatterns: this.options.customSpamPatterns
+    };
+
+    if (this.options.checkMxRecords) {
+      return fullValidationAsync(email, validationOptions);
+    }
+
+    return fullValidation(email, validationOptions);
+  }
+
+  /**
+   * Quick validation - format only
+   * @param {string} email - Email to validate
+   * @returns {boolean} True if valid format
+   */
+  isValid(email) {
+    return isValidEmail(email);
+  }
+
+  /**
+   * Check if temporary email
+   * @param {string} email - Email to check
+   * @returns {boolean} True if temporary
+   */
+  isTemporary(email) {
+    return isTempEmail(email);
+  }
+
+  /**
+   * Check if spam email
+   * @param {string} email - Email to check
+   * @returns {boolean} True if spam
+   */
+  isSpam(email) {
+    return isSpam(email, this.options.spamThreshold);
+  }
+
+  /**
+   * Add custom disposable domains
+   * @param {string[]} domains - Domains to add
+   */
+  addTempDomains(domains) {
+    addDisposableDomains(domains);
+  }
+}
+
+// Export everything
+module.exports = {
+  // Main validation functions
+  validateEmail,
+  validateEmailAsync,
+  fullValidation,
+  fullValidationAsync,
+  
+  // Quick validators
+  isValidEmail,
+  isTempEmail,
+  isTemporaryEmail,
+  isSpam,
+  isSpamEmail,
+  
+  // Utility functions
+  normalizeEmail,
+  extractDomain,
+  extractLocal,
+  
+  // Domain checks
+  isDisposableDomain,
+  isSuspiciousDomain,
+  addDisposableDomains,
+  getDisposableDomainCount,
+  
+  // MX validation
+  checkMxRecords,
+  validateEmailMx,
+  batchCheckMxRecords,
+  
+  // Scoring
+  getSpamScore,
+  
+  // Class for custom configuration
+  EmailValidator,
+  
+  // Constants (for advanced users)
+  DISPOSABLE_DOMAINS,
+  EMAIL_REGEX,
+  SIMPLE_EMAIL_REGEX,
+  VALID_TLDS,
+  SPAM_LOCAL_PATTERNS,
+  SPAM_DOMAIN_PATTERNS
+};