bouncevalidator 0.0.1

package/dist/index.d.mts

@@ -0,0 +1,398 @@
+/**
+ * Reachability status of an email address
+ */
+type Reachability = "safe" | "invalid" | "risky" | "unknown";
+/**
+ * Syntax validation result
+ */
+interface SyntaxResult {
+    /** The original email address */
+    address: string;
+    /** The domain part of the email */
+    domain: string;
+    /** The username/local part of the email */
+    username: string;
+    /** Whether the email has valid syntax */
+    isValidSyntax: boolean;
+    /** Normalized email address (lowercase, trimmed) */
+    normalizedEmail: string;
+    /** Suggested correction for common typos */
+    suggestion: string | null;
+}
+/**
+ * MX record verification result
+ */
+interface MxResult {
+    /** Whether the domain accepts mail */
+    acceptsMail: boolean;
+    /** List of MX records found */
+    records: string[];
+}
+/**
+ * SMTP error information
+ */
+interface SmtpError {
+    /** Type of error encountered */
+    type: string;
+    /** Human-readable error message */
+    message: string;
+}
+/**
+ * SMTP verification result
+ */
+interface SmtpResult {
+    /** Whether SMTP verification was successful */
+    canConnectSmtp: boolean;
+    /** Whether the mailbox exists */
+    isDeliverable: boolean;
+    /** Whether the server is a catch-all */
+    isCatchAll: boolean;
+    /** Error information if verification failed */
+    error: SmtpError | null;
+}
+/**
+ * Miscellaneous email information
+ */
+interface MiscResult {
+    /** Whether the email is from a disposable domain */
+    isDisposable: boolean;
+    /** Whether the email is a role-based account */
+    isRoleAccount: boolean;
+    /** Whether the email is from a free provider */
+    isFreeProvider: boolean;
+    /** Gravatar URL if available */
+    gravatarUrl: string | null;
+}
+/**
+ * Complete email validation result
+ */
+interface ValidationResult {
+    /** The original input email */
+    input: string;
+    /** Overall reachability status */
+    isReachable: Reachability;
+    /** Syntax validation result */
+    syntax: SyntaxResult;
+    /** MX record verification result */
+    mx: MxResult;
+    /** SMTP verification result */
+    smtp: SmtpResult;
+    /** Miscellaneous information */
+    misc: MiscResult;
+}
+/**
+ * Configuration options for email validation
+ */
+interface ValidationOptions {
+    /** SMTP connection timeout in milliseconds (default: 10000) */
+    smtpTimeout?: number;
+    /** Whether to perform SMTP verification (default: true) */
+    verifySmtp?: boolean;
+    /** Whether to check for disposable emails (default: true) */
+    checkDisposable?: boolean;
+    /** Whether to check for role-based accounts (default: true) */
+    checkRoleAccount?: boolean;
+    /** Whether to check for free providers (default: true) */
+    checkFreeProvider?: boolean;
+    /** Whether to check for Gravatar (default: false) */
+    checkGravatar?: boolean;
+    /** Custom HELO/EHLO hostname */
+    heloHost?: string;
+    /** Custom sender address for MAIL FROM */
+    senderAddress?: string;
+    /** DNS cache TTL in milliseconds (default: 300000 = 5 minutes) */
+    dnsCacheTtl?: number;
+    /** Whether to use DNS cache (default: true) */
+    useDnsCache?: boolean;
+    /** Whether to detect catch-all domains (default: true) */
+    detectCatchAll?: boolean;
+    /** Proxy configuration for SMTP connections */
+    proxy?: {
+        host: string;
+        port: number;
+        type: "socks4" | "socks5" | "http";
+    };
+}
+/**
+ * Options for bulk validation
+ */
+interface BulkValidationOptions extends ValidationOptions {
+    /** Maximum concurrent validations (default: 5) */
+    concurrency?: number;
+    /** Delay between validations in milliseconds (default: 0) */
+    delayBetween?: number;
+    /** Callback for progress updates */
+    onProgress?: (completed: number, total: number, result: ValidationResult) => void;
+}
+/**
+ * DNS cache entry
+ */
+interface DnsCacheEntry {
+    /** Cached MX records */
+    records: string[];
+    /** Whether the domain accepts mail */
+    acceptsMail: boolean;
+    /** Timestamp when the entry was cached */
+    timestamp: number;
+}
+
+/**
+ * Validate email syntax
+ * @param email The email address to validate
+ * @returns SyntaxResult with validation details
+ */
+declare function validateSyntax(email: string): SyntaxResult;
+/**
+ * Quick check if an email has valid syntax
+ * @param email The email to check
+ * @returns true if syntax is valid
+ */
+declare function isValidSyntax(email: string): boolean;
+
+/**
+ * Simple in-memory DNS cache with TTL support
+ */
+declare class DnsCache {
+    private cache;
+    private ttl;
+    /**
+     * Create a new DNS cache
+     * @param ttl Time-to-live in milliseconds (default: 5 minutes)
+     */
+    constructor(ttl?: number);
+    /**
+     * Get a cached entry for a domain
+     * @param domain The domain to look up
+     * @returns The cached entry or null if not found/expired
+     */
+    get(domain: string): DnsCacheEntry | null;
+    /**
+     * Set a cache entry for a domain
+     * @param domain The domain to cache
+     * @param records The MX records
+     * @param acceptsMail Whether the domain accepts mail
+     */
+    set(domain: string, records: string[], acceptsMail: boolean): void;
+    /**
+     * Clear all cached entries
+     */
+    clear(): void;
+    /**
+     * Remove expired entries from the cache
+     */
+    cleanup(): void;
+    /**
+     * Get the number of cached entries
+     */
+    get size(): number;
+    /**
+     * Set the TTL for the cache
+     * @param ttl Time-to-live in milliseconds
+     */
+    setTtl(ttl: number): void;
+}
+declare const globalDnsCache: DnsCache;
+
+/**
+ * Verify MX records for a domain
+ * @param domain The domain to verify
+ * @param options Validation options
+ * @returns MxResult with verification details
+ */
+declare function verifyMx(domain: string, options?: ValidationOptions, cache?: DnsCache): Promise<MxResult>;
+/**
+ * Check if a domain has valid MX records
+ * @param domain The domain to check
+ * @returns true if domain has valid MX records
+ */
+declare function hasMxRecords(domain: string): Promise<boolean>;
+/**
+ * Get MX records for a domain, sorted by priority
+ * @param domain The domain to lookup
+ * @returns Array of MX hostnames sorted by priority
+ */
+declare function getMxRecords(domain: string): Promise<string[]>;
+
+/**
+ * Check if an email is from a disposable domain
+ */
+declare function checkDisposable(domain: string): boolean;
+/**
+ * Check if an email is a role-based account
+ */
+declare function checkRoleAccount(username: string): boolean;
+/**
+ * Check if an email is from a free provider
+ */
+declare function checkFreeProvider(domain: string): boolean;
+/**
+ * Perform miscellaneous checks on an email
+ * @param email The email address
+ * @param options Validation options
+ * @returns MiscResult with check results
+ */
+declare function checkMisc(email: string, options?: ValidationOptions): Promise<MiscResult>;
+
+/**
+ * Normalize an email address
+ * - Trims whitespace
+ * - Converts to lowercase
+ * - Removes dots from Gmail usernames (optional)
+ *
+ * @param email The email to normalize
+ * @param options Normalization options
+ * @returns Normalized email address
+ */
+declare function normalizeEmail(email: string, options?: {
+    /** Remove dots from Gmail-style addresses */
+    removeDots?: boolean;
+    /** Remove plus addressing suffix */
+    removePlusAddressing?: boolean;
+}): string;
+/**
+ * Extract parts from an email address
+ * @param email The email address
+ * @returns Object with username and domain, or null if invalid
+ */
+declare function extractParts(email: string): {
+    username: string;
+    domain: string;
+} | null;
+
+/**
+ * Get a suggested correction for a domain
+ * @param domain The domain to check for typos
+ * @returns Suggested domain or null if no suggestion
+ */
+declare function getSuggestion(domain: string): string | null;
+/**
+ * Get a suggestion for the full email address
+ * @param email The email to check for typos
+ * @returns Suggested email or null if no suggestion
+ */
+declare function getEmailSuggestion(email: string): string | null;
+
+/**
+ * SMTP error types
+ */
+declare const SmtpErrorType: {
+    readonly CONNECTION_FAILED: "ConnectionFailed";
+    readonly TIMEOUT: "Timeout";
+    readonly INVALID_RESPONSE: "InvalidResponse";
+    readonly HELO_FAILED: "HeloFailed";
+    readonly MAIL_FROM_FAILED: "MailFromFailed";
+    readonly RCPT_TO_FAILED: "RcptToFailed";
+    readonly MAILBOX_NOT_FOUND: "MailboxNotFound";
+    readonly MAILBOX_DISABLED: "MailboxDisabled";
+    readonly GREYLISTED: "Greylisted";
+    readonly BLOCKED: "Blocked";
+    readonly UNKNOWN: "Unknown";
+};
+/**
+ * Try SMTP verification against multiple MX hosts
+ * Falls back to the next host if the first fails
+ */
+declare function verifySmtpWithFallback(email: string, mxHosts: string[], options?: ValidationOptions): Promise<SmtpResult>;
+
+/**
+ * List of known disposable email domains
+ * This list includes temporary email services that should be flagged
+ */
+declare const disposableDomains: Set<string>;
+/**
+ * Check if a domain is a known disposable email domain
+ */
+declare function isDisposableDomain(domain: string): boolean;
+
+/**
+ * List of known role-based email prefixes
+ * These are email addresses that typically go to a group or role rather than an individual
+ */
+declare const rolePrefixes: Set<string>;
+/**
+ * Check if an email prefix is a role-based account
+ */
+declare function isRolePrefix(prefix: string): boolean;
+
+/**
+ * List of known free email providers
+ * These are legitimate email services that offer free accounts
+ */
+declare const freeProviders: Set<string>;
+/**
+ * Check if a domain is a known free email provider
+ */
+declare function isFreeProvider(domain: string): boolean;
+
+/**
+ * Validate a single email address
+ *
+ * @param email The email address to validate
+ * @param options Validation options
+ * @returns Promise resolving to ValidationResult
+ *
+ * @example
+ * ```typescript
+ * import { validate } from 'bouncevalidator';
+ *
+ * const result = await validate('user@example.com');
+ * console.log(result.isReachable); // 'safe', 'invalid', 'risky', or 'unknown'
+ * ```
+ */
+declare function validate(email: string, options?: ValidationOptions): Promise<ValidationResult>;
+/**
+ * Validate multiple email addresses
+ *
+ * @param emails Array of email addresses to validate
+ * @param options Bulk validation options
+ * @returns Promise resolving to array of ValidationResults
+ *
+ * @example
+ * ```typescript
+ * import { validateBulk } from 'bouncevalidator';
+ *
+ * const results = await validateBulk([
+ *   'user1@example.com',
+ *   'user2@example.com'
+ * ], { concurrency: 5 });
+ * ```
+ */
+declare function validateBulk(emails: string[], options?: BulkValidationOptions): Promise<ValidationResult[]>;
+/**
+ * Quick validation - only checks syntax and MX records
+ * Much faster than full validation as it skips SMTP verification
+ *
+ * @param email The email address to validate
+ * @returns Promise resolving to ValidationResult
+ */
+declare function validateQuick(email: string): Promise<ValidationResult>;
+/**
+ * Clear the DNS cache
+ */
+declare function clearDnsCache(): void;
+/**
+ * Get the current DNS cache size
+ */
+declare function getDnsCacheSize(): number;
+declare const _default: {
+    validate: typeof validate;
+    validateBulk: typeof validateBulk;
+    validateQuick: typeof validateQuick;
+    clearDnsCache: typeof clearDnsCache;
+    getDnsCacheSize: typeof getDnsCacheSize;
+    normalizeEmail: typeof normalizeEmail;
+    extractParts: typeof extractParts;
+    getSuggestion: typeof getSuggestion;
+    getEmailSuggestion: typeof getEmailSuggestion;
+    validateSyntax: typeof validateSyntax;
+    isValidSyntax: typeof isValidSyntax;
+    verifyMx: typeof verifyMx;
+    hasMxRecords: typeof hasMxRecords;
+    getMxRecords: typeof getMxRecords;
+    checkMisc: typeof checkMisc;
+    checkDisposable: typeof checkDisposable;
+    checkRoleAccount: typeof checkRoleAccount;
+    checkFreeProvider: typeof checkFreeProvider;
+};
+
+export { type BulkValidationOptions, DnsCache, type DnsCacheEntry, type MiscResult, type MxResult, type Reachability, type SmtpError, SmtpErrorType, type SmtpResult, type SyntaxResult, type ValidationOptions, type ValidationResult, checkDisposable, checkFreeProvider, checkMisc, checkRoleAccount, clearDnsCache, _default as default, disposableDomains, extractParts, freeProviders, getDnsCacheSize, getEmailSuggestion, getMxRecords, getSuggestion, globalDnsCache, hasMxRecords, isDisposableDomain, isFreeProvider, isRolePrefix, isValidSyntax, normalizeEmail, rolePrefixes, validate, validateBulk, validateQuick, validateSyntax, verifyMx, verifySmtpWithFallback as verifySmtp };