@mikkelscheike/email-provider-links 4.0.11 → 5.1.0

package/dist/api.js

@@ -6,14 +6,81 @@
  * Clean function names and enhanced error context.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.Config = void 0;
+exports.Config = exports.emailsMatch = exports.normalizeEmail = void 0;
 exports.getEmailProvider = getEmailProvider;
 exports.getEmailProviderSync = getEmailProviderSync;
-exports.normalizeEmail = normalizeEmail;
-exports.emailsMatch = emailsMatch;
 exports.getEmailProviderFast = getEmailProviderFast;
 const concurrent_dns_1 = require("./concurrent-dns");
 const provider_loader_1 = require("./provider-loader");
+const idn_1 = require("./idn");
+const alias_detection_1 = require("./alias-detection");
+let cachedProvidersRef = null;
+let cachedDomainMap = null;
+function getDomainMapFromProviders(providers) {
+    if (cachedProvidersRef === providers && cachedDomainMap) {
+        return cachedDomainMap;
+    }
+    const domainMap = new Map();
+    for (const loadedProvider of providers) {
+        for (const domain of loadedProvider.domains) {
+            domainMap.set(domain.toLowerCase(), loadedProvider);
+        }
+    }
+    cachedProvidersRef = providers;
+    cachedDomainMap = domainMap;
+    return domainMap;
+}
+function validateAndParseEmailForLookup(email) {
+    if (!email || typeof email !== 'string') {
+        return {
+            ok: false,
+            email: email || '',
+            error: {
+                type: 'INVALID_EMAIL',
+                message: 'Email address is required and must be a string'
+            }
+        };
+    }
+    const trimmedEmail = email.trim();
+    // Strict validation: treat any IDN validation failure as invalid input.
+    // Only surface IDN_VALIDATION_ERROR for true encoding issues.
+    const idnError = (0, idn_1.validateInternationalEmail)(trimmedEmail);
+    if (idnError) {
+        if (idnError.code === idn_1.IDNValidationError.INVALID_ENCODING) {
+            return {
+                ok: false,
+                email: trimmedEmail,
+                error: {
+                    type: 'IDN_VALIDATION_ERROR',
+                    message: idnError.message,
+                    idnError: idnError.code
+                }
+            };
+        }
+        return {
+            ok: false,
+            email: trimmedEmail,
+            error: {
+                type: 'INVALID_EMAIL',
+                message: 'Invalid email format'
+            }
+        };
+    }
+    const atIndex = trimmedEmail.lastIndexOf('@');
+    if (atIndex === -1) {
+        return {
+            ok: false,
+            email: trimmedEmail,
+            error: {
+                type: 'INVALID_EMAIL',
+                message: 'Invalid email format'
+            }
+        };
+    }
+    const domainRaw = trimmedEmail.slice(atIndex + 1).toLowerCase();
+    const domain = (0, idn_1.domainToPunycode)(domainRaw);
+    return { ok: true, trimmedEmail, domain };
+}
 /**
  * Get email provider information for any email address.
  *
@@ -46,46 +113,28 @@ const provider_loader_1 = require("./provider-loader");
  */
 async function getEmailProvider(email, timeout) {
     try {
-        // Input validation
-        if (!email || typeof email !== 'string') {
-            return {
-                provider: null,
-                email: email || '',
-                loginUrl: null,
-                error: {
-                    type: 'INVALID_EMAIL',
-                    message: 'Email address is required and must be a string'
-                }
-            };
-        }
-        // Basic email format validation
-        const emailRegex = /^[^\s@]+@[^\s@]+\.[^\s@]+$/;
-        if (!emailRegex.test(email)) {
-            return {
-                provider: null,
-                email,
-                loginUrl: null,
-                error: {
-                    type: 'INVALID_EMAIL',
-                    message: 'Invalid email format'
-                }
-            };
-        }
-        const domain = email.split('@')[1]?.toLowerCase();
-        if (!domain) {
+        const parsed = validateAndParseEmailForLookup(email);
+        if (!parsed.ok) {
+            // Try to normalize even invalid emails (may help with some edge cases)
+            let normalizedEmail = parsed.email;
+            try {
+                normalizedEmail = (0, alias_detection_1.normalizeEmail)(parsed.email);
+            }
+            catch {
+                // If normalization fails, use original email
+            }
             return {
                 provider: null,
-                email,
+                email: normalizedEmail,
                 loginUrl: null,
-                error: {
-                    type: 'INVALID_EMAIL',
-                    message: 'Invalid email format - missing domain'
-                }
+                error: parsed.error
             };
         }
+        const domain = parsed.domain;
         // First try synchronous domain matching
         const syncResult = getEmailProviderSync(email);
         if (syncResult.provider) {
+            // Email is already normalized in getEmailProviderSync
             return {
                 ...syncResult,
                 detectionMethod: 'domain_match'
@@ -110,9 +159,18 @@ async function getEmailProvider(email, timeout) {
             enableParallel: true,
             collectDebugInfo: false
         });
+        // Normalize email using alias detection (even if no provider found)
+        // This ensures consistent email format regardless of provider detection result
+        let normalizedEmail = email;
+        try {
+            normalizedEmail = (0, alias_detection_1.normalizeEmail)(email);
+        }
+        catch {
+            // If normalization fails, use original email
+        }
         const result = {
             provider: concurrentResult.provider,
-            email,
+            email: normalizedEmail,
             loginUrl: concurrentResult.provider?.loginUrl || null,
             detectionMethod: concurrentResult.detectionMethod || 'mx_record'
         };
@@ -130,9 +188,9 @@ async function getEmailProvider(email, timeout) {
     }
     catch (error) {
         // Enhanced error handling
-        if (error.message?.includes('Rate limit exceeded')) {
+        if (error instanceof Error && error.message.includes('Rate limit exceeded')) {
             const retryMatch = error.message.match(/Try again in (\d+) seconds/);
-            const retryAfter = retryMatch ? parseInt(retryMatch[1], 10) : undefined;
+            const retryAfter = retryMatch?.[1] ? parseInt(retryMatch[1], 10) : undefined;
             return {
                 provider: null,
                 email,
@@ -144,7 +202,7 @@ async function getEmailProvider(email, timeout) {
                 }
             };
         }
-        if (error.message?.includes('timeout')) {
+        if (error instanceof Error && error.message.includes('timeout')) {
             return {
                 provider: null,
                 email,
@@ -161,7 +219,7 @@ async function getEmailProvider(email, timeout) {
             loginUrl: null,
             error: {
                 type: 'NETWORK_ERROR',
-                message: error.message || 'Unknown network error'
+                message: error instanceof Error ? error.message : 'Unknown network error'
             }
         };
     }
@@ -189,44 +247,24 @@ async function getEmailProvider(email, timeout) {
  */
 function getEmailProviderSync(email) {
     try {
-        // Input validation
-        if (!email || typeof email !== 'string') {
-            return {
-                provider: null,
-                email: email || '',
-                loginUrl: null,
-                error: {
-                    type: 'INVALID_EMAIL',
-                    message: 'Email address is required and must be a string'
-                }
-            };
-        }
-        // Basic email format validation
-        const emailRegex = /^[^\s@]+@[^\s@]+\.[^\s@]+$/;
-        if (!emailRegex.test(email)) {
-            return {
-                provider: null,
-                email,
-                loginUrl: null,
-                error: {
-                    type: 'INVALID_EMAIL',
-                    message: 'Invalid email format'
-                }
-            };
-        }
-        // Pure synchronous domain matching
-        const domain = email.split('@')[1]?.toLowerCase();
-        if (!domain) {
+        const parsed = validateAndParseEmailForLookup(email);
+        if (!parsed.ok) {
+            // Try to normalize even invalid emails (may help with some edge cases)
+            let normalizedEmail = parsed.email;
+            try {
+                normalizedEmail = (0, alias_detection_1.normalizeEmail)(parsed.email);
+            }
+            catch {
+                // If normalization fails, use original email
+            }
             return {
                 provider: null,
-                email,
+                email: normalizedEmail,
                 loginUrl: null,
-                error: {
-                    type: 'INVALID_EMAIL',
-                    message: 'Invalid email format - missing domain'
-                }
+                error: parsed.error
             };
         }
+        const domain = parsed.domain;
         // Load providers with verification
         let provider = null;
         try {
@@ -246,13 +284,7 @@ function getEmailProviderSync(email) {
                     }
                 };
             }
-            const domainMap = new Map();
-            // Build domain map from loaded providers
-            for (const loadedProvider of result.providers) {
-                for (const domain of loadedProvider.domains) {
-                    domainMap.set(domain.toLowerCase(), loadedProvider);
-                }
-            }
+            const domainMap = getDomainMapFromProviders(result.providers);
             provider = domainMap.get(domain) || null;
         }
         catch (error) {
@@ -269,9 +301,18 @@ function getEmailProviderSync(email) {
                 }
             };
         }
+        // Normalize email using alias detection (even if no provider found)
+        // This ensures consistent email format regardless of provider detection result
+        let normalizedEmail = email;
+        try {
+            normalizedEmail = (0, alias_detection_1.normalizeEmail)(email);
+        }
+        catch {
+            // If normalization fails, use original email
+        }
         const result = {
             provider: provider || null,
-            email,
+            email: normalizedEmail,
             loginUrl: provider?.loginUrl || null,
             detectionMethod: 'domain_match'
         };
@@ -291,105 +332,15 @@ function getEmailProviderSync(email) {
             loginUrl: null,
             error: {
                 type: 'INVALID_EMAIL',
-                message: error.message || 'Invalid email address'
+                message: error instanceof Error ? error.message : 'Invalid email address'
             }
         };
     }
 }
-/**
- * Normalize an email address to its canonical form.
- *
- * This handles provider-specific aliasing rules:
- * - Gmail: removes dots and plus addressing
- * - Other providers: removes plus addressing only
- *
- * @param email - The email address to normalize
- * @returns The canonical email address
- *
- * @example
- * ```typescript
- * const canonical = normalizeEmail('L.O.C.A.L+work@DOMAIN.TLD');
- * console.log(canonical); // 'local@domain.tld'
- *
- * const provider = normalizeEmail('local+newsletter@provider.tld');
- * console.log(provider); // 'local@provider.tld'
- * ```
- */
-function normalizeEmail(email) {
-    if (!email || typeof email !== 'string') {
-        return email;
-    }
-    // Convert to lowercase
-    const lowercaseEmail = email.toLowerCase().trim();
-    // Split email into local and domain parts
-    const atIndex = lowercaseEmail.lastIndexOf('@');
-    if (atIndex === -1) {
-        return lowercaseEmail;
-    }
-    let localPart = lowercaseEmail.slice(0, atIndex);
-    const domainPart = lowercaseEmail.slice(atIndex + 1);
-    // Use providers for domain lookup
-    let provider = null;
-    try {
-        const result = (0, provider_loader_1.loadProviders)();
-        if (!result.success) {
-            return lowercaseEmail; // Return as-is if providers can't be loaded
-        }
-        const domainMap = new Map();
-        for (const loadedProvider of result.providers) {
-            for (const domain of loadedProvider.domains) {
-                domainMap.set(domain.toLowerCase(), loadedProvider);
-            }
-        }
-        provider = domainMap.get(domainPart) || null;
-    }
-    catch (error) {
-        return lowercaseEmail; // Return as-is if error occurs
-    }
-    if (provider?.alias) {
-        // Provider supports aliasing
-        if (provider.alias.dots) {
-            // Remove all dots from local part (e.g. Gmail)
-            localPart = localPart.replace(/\./g, '');
-        }
-        if (provider.alias.plus) {
-            // Remove plus addressing (everything after +)
-            const plusIndex = localPart.indexOf('+');
-            if (plusIndex !== -1) {
-                localPart = localPart.slice(0, plusIndex);
-            }
-        }
-    }
-    return `${localPart}@${domainPart}`;
-}
-/**
- * Check if two email addresses are the same person (accounting for aliases).
- *
- * This normalizes both emails and compares their canonical forms.
- * Useful for preventing duplicate accounts and matching login attempts.
- *
- * @param email1 - First email address
- * @param email2 - Second email address
- * @returns true if the emails represent the same person
- *
- * @example
- * ```typescript
- * const match = emailsMatch('local@domain.tld', 'l.o.c.a.l+work@domain.tld');
- * console.log(match); // true
- *
- * const different = emailsMatch('local@domain.tld', 'other@domain.tld');
- * console.log(different); // false
- * ```
- */
-function emailsMatch(email1, email2) {
-    if (!email1 || !email2 || typeof email1 !== 'string' || typeof email2 !== 'string') {
-        return false;
-    }
-    // Normalize both emails and compare
-    const normalized1 = normalizeEmail(email1);
-    const normalized2 = normalizeEmail(email2);
-    return normalized1 === normalized2;
-}
+// Re-export alias detection functions from the dedicated module
+var alias_detection_2 = require("./alias-detection");
+Object.defineProperty(exports, "normalizeEmail", { enumerable: true, get: function () { return alias_detection_2.normalizeEmail; } });
+Object.defineProperty(exports, "emailsMatch", { enumerable: true, get: function () { return alias_detection_2.emailsMatch; } });
 /**
  * Enhanced email provider detection with concurrent DNS for maximum performance.
  * This function uses parallel MX/TXT lookups for 2x faster business domain detection.
@@ -414,46 +365,21 @@ function emailsMatch(email1, email2) {
 async function getEmailProviderFast(email, options = {}) {
     const { timeout = 5000, enableParallel = true, collectDebugInfo = false } = options;
     try {
-        // Input validation
-        if (!email || typeof email !== 'string') {
+        const parsed = validateAndParseEmailForLookup(email);
+        if (!parsed.ok) {
             return {
                 provider: null,
-                email: email || '',
+                email: parsed.email,
                 loginUrl: null,
-                error: {
-                    type: 'INVALID_EMAIL',
-                    message: 'Email address is required and must be a string'
-                }
-            };
-        }
-        // Basic email format validation
-        const emailRegex = /^[^\s@]+@[^\s@]+\.[^\s@]+$/;
-        if (!emailRegex.test(email)) {
-            return {
-                provider: null,
-                email,
-                loginUrl: null,
-                error: {
-                    type: 'INVALID_EMAIL',
-                    message: 'Invalid email format'
-                }
-            };
-        }
-        const domain = email.split('@')[1]?.toLowerCase();
-        if (!domain) {
-            return {
-                provider: null,
-                email,
-                loginUrl: null,
-                error: {
-                    type: 'INVALID_EMAIL',
-                    message: 'Invalid email format - missing domain'
-                }
+                error: parsed.error
             };
         }
+        const domain = parsed.domain;
+        const trimmedEmail = parsed.trimmedEmail;
         // First try standard domain matching (fast path)
-        const syncResult = getEmailProviderSync(email);
+        const syncResult = getEmailProviderSync(trimmedEmail);
         if (syncResult.provider) {
+            // Email is already normalized in getEmailProviderSync
             return {
                 ...syncResult,
                 detectionMethod: 'domain_match',
@@ -466,7 +392,7 @@ async function getEmailProviderFast(email, options = {}) {
         if (!result.success) {
             return {
                 provider: null,
-                email,
+                email: trimmedEmail,
                 loginUrl: null,
                 error: {
                     type: 'NETWORK_ERROR',
@@ -480,9 +406,18 @@ async function getEmailProviderFast(email, options = {}) {
             enableParallel,
             collectDebugInfo
         });
+        // Normalize email using alias detection (even if no provider found)
+        // This ensures consistent email format regardless of provider detection result
+        let normalizedEmail = trimmedEmail;
+        try {
+            normalizedEmail = (0, alias_detection_1.normalizeEmail)(trimmedEmail);
+        }
+        catch {
+            // If normalization fails, use original email
+        }
         const fastResult = {
             provider: concurrentResult.provider,
-            email,
+            email: normalizedEmail,
             loginUrl: concurrentResult.provider?.loginUrl || null,
             detectionMethod: concurrentResult.detectionMethod || 'mx_record',
             timing: concurrentResult.timing,
@@ -505,7 +440,7 @@ async function getEmailProviderFast(email, options = {}) {
             loginUrl: null,
             error: {
                 type: 'NETWORK_ERROR',
-                message: error.message || 'DNS detection failed'
+                message: error instanceof Error ? error.message : 'DNS detection failed'
             }
         };
     }

package/dist/concurrent-dns.d.ts

@@ -5,6 +5,10 @@
  * Uses Promise.allSettled for fault tolerance and intelligent result merging.
  */
 import { EmailProvider } from './api';
+type MXRecordLike = {
+    exchange?: string;
+};
+type TXTRecordLike = string;
 /**
  * Configuration for concurrent DNS detection
  */
@@ -29,13 +33,13 @@ export interface DNSQueryResult {
     /** Whether the query succeeded */
     success: boolean;
     /** DNS records returned (if successful) */
-    records?: any[];
+    records?: MXRecordLike[] | TXTRecordLike[];
     /** Error information (if failed) */
     error?: Error;
     /** Query execution time in milliseconds */
     timing: number;
     /** Raw DNS response for debugging */
-    rawResponse?: any;
+    rawResponse?: unknown;
 }
 /**
  * Result from concurrent DNS detection
@@ -130,4 +134,5 @@ export declare function createConcurrentDNSDetector(providers: EmailProvider[],
  * Utility function for quick concurrent DNS detection
  */
 export declare function detectProviderConcurrent(domain: string, providers: EmailProvider[], config?: Partial<ConcurrentDNSConfig>): Promise<ConcurrentDNSResult>;
+export {};
 //# sourceMappingURL=concurrent-dns.d.ts.map

package/dist/concurrent-dns.js

@@ -295,6 +295,8 @@ class ConcurrentDNSDetector {
         let confidence = 0;
         if (query.type === 'mx' && detection.mxPatterns) {
             for (const record of query.records) {
+                if (typeof record !== 'object' || record === null)
+                    continue;
                 const exchange = record.exchange?.toLowerCase() || '';
                 for (const pattern of detection.mxPatterns) {
                     if (exchange.includes(pattern.toLowerCase())) {
@@ -306,6 +308,8 @@ class ConcurrentDNSDetector {
         }
         else if (query.type === 'txt' && detection.txtPatterns) {
             for (const record of query.records) {
+                if (typeof record !== 'string')
+                    continue;
                 const txtRecord = record.toLowerCase();
                 for (const pattern of detection.txtPatterns) {
                     if (txtRecord.includes(pattern.toLowerCase())) {
@@ -368,6 +372,8 @@ class ConcurrentDNSDetector {
         if (!mxQuery?.records)
             return null;
         for (const record of mxQuery.records) {
+            if (typeof record !== 'object' || record === null)
+                continue;
             const exchange = record.exchange?.toLowerCase() || '';
             for (const provider of this.providers) {
                 if (provider.type === 'proxy_service' && provider.customDomainDetection?.mxPatterns) {
@@ -402,9 +408,11 @@ class ConcurrentDNSDetector {
             return Promise.reject(new Error(`DNS query timeout after ${ms}ms`));
         }
         let rejectFn;
+        let queryEntry;
         const wrappedPromise = new Promise((resolve, reject) => {
             rejectFn = reject;
-            const timeout = setTimeout(() => reject(new Error(`DNS query timeout after ${ms}ms`)), ms).unref();
+            const timeout = setTimeout(() => reject(new Error(`DNS query timeout after ${ms}ms`)), ms);
+            timeout.unref?.();
             // Start the underlying operation only after setting up the timeout
             fn()
                 .then(resolve)
@@ -412,7 +420,6 @@ class ConcurrentDNSDetector {
                 .finally(() => {
                 clearTimeout(timeout);
                 // Clean up active query
-                const queryEntry = Array.from(this.activeQueries).find(entry => entry.promise === wrappedPromise);
                 if (queryEntry) {
                     this.activeQueries.delete(queryEntry);
                 }
@@ -420,7 +427,7 @@ class ConcurrentDNSDetector {
         });
         // Track active query for potential cleanup in tests
         if (rejectFn) {
-            const queryEntry = { promise: wrappedPromise, reject: rejectFn };
+            queryEntry = { promise: wrappedPromise, reject: rejectFn };
             this.activeQueries.add(queryEntry);
         }
         return wrappedPromise;

package/dist/constants.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Email validation constants based on RFC 5321
+ *
+ * These limits are defined in RFC 5321 Section 4.5.3.1:
+ * - Maximum total email length: 254 characters
+ * - Maximum local part length: 64 characters
+ * - Maximum domain length: 253 characters
+ */
+export declare const EmailLimits: {
+    /** Maximum total email address length (local + @ + domain) */
+    readonly MAX_EMAIL_LENGTH: 254;
+    /** Maximum local part length (before @) */
+    readonly MAX_LOCAL_PART_LENGTH: 64;
+    /** Maximum domain length (after @) */
+    readonly MAX_DOMAIN_LENGTH: 253;
+};
+/**
+ * Memory calculation constants
+ */
+export declare const MemoryConstants: {
+    /** Bytes per kilobyte */
+    readonly BYTES_PER_KB: 1024;
+    /** Kilobytes per megabyte */
+    readonly KB_PER_MB: 1024;
+};
+//# sourceMappingURL=constants.d.ts.map

package/dist/constants.js

@@ -0,0 +1,29 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MemoryConstants = exports.EmailLimits = void 0;
+/**
+ * Email validation constants based on RFC 5321
+ *
+ * These limits are defined in RFC 5321 Section 4.5.3.1:
+ * - Maximum total email length: 254 characters
+ * - Maximum local part length: 64 characters
+ * - Maximum domain length: 253 characters
+ */
+exports.EmailLimits = {
+    /** Maximum total email address length (local + @ + domain) */
+    MAX_EMAIL_LENGTH: 254,
+    /** Maximum local part length (before @) */
+    MAX_LOCAL_PART_LENGTH: 64,
+    /** Maximum domain length (after @) */
+    MAX_DOMAIN_LENGTH: 253,
+};
+/**
+ * Memory calculation constants
+ */
+exports.MemoryConstants = {
+    /** Bytes per kilobyte */
+    BYTES_PER_KB: 1024,
+    /** Kilobytes per megabyte */
+    KB_PER_MB: 1024,
+};
+//# sourceMappingURL=constants.js.map

package/dist/error-utils.d.ts

@@ -0,0 +1,56 @@
+/**
+ * Error handling utilities
+ *
+ * Provides consistent error handling patterns across the codebase.
+ */
+/**
+ * Extracts a human-readable error message from an unknown error value.
+ *
+ * @param error - The error value (Error, string, or unknown)
+ * @returns A string error message
+ *
+ * @example
+ * ```typescript
+ * try {
+ *   // some operation
+ * } catch (error: unknown) {
+ *   const message = getErrorMessage(error);
+ *   console.error(message);
+ * }
+ * ```
+ */
+export declare function getErrorMessage(error: unknown): string;
+/**
+ * Extracts an error code from an unknown error value.
+ *
+ * @param error - The error value
+ * @returns The error code if available, undefined otherwise
+ *
+ * @example
+ * ```typescript
+ * try {
+ *   // some operation
+ * } catch (error: unknown) {
+ *   const code = getErrorCode(error);
+ *   if (code === 'ENOENT') {
+ *     // handle file not found
+ *   }
+ * }
+ * ```
+ */
+export declare function getErrorCode(error: unknown): string | undefined;
+/**
+ * Checks if an error is a file not found error (ENOENT).
+ *
+ * @param error - The error value
+ * @returns true if the error is a file not found error
+ */
+export declare function isFileNotFoundError(error: unknown): boolean;
+/**
+ * Checks if an error is a JSON parsing error.
+ *
+ * @param error - The error value
+ * @returns true if the error is a JSON parsing error
+ */
+export declare function isJsonError(error: unknown): boolean;
+//# sourceMappingURL=error-utils.d.ts.map