@mikkelscheike/email-provider-links 5.0.0 → 5.1.1

package/dist/api.js

@@ -6,15 +6,14 @@
  * 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) {
@@ -82,6 +81,18 @@ function validateAndParseEmailForLookup(email) {
     const domain = (0, idn_1.domainToPunycode)(domainRaw);
     return { ok: true, trimmedEmail, domain };
 }
+/**
+ * Convert a full EmailProvider to a simplified version
+ */
+function simplifyProvider(provider) {
+    if (!provider)
+        return null;
+    return {
+        companyProvider: provider.companyProvider,
+        loginUrl: provider.loginUrl,
+        type: provider.type
+    };
+}
 /**
  * Get email provider information for any email address.
  *
@@ -90,16 +101,22 @@ function validateAndParseEmailForLookup(email) {
  * - Business domains (mycompany.com using Google Workspace, etc.)
  * - Unknown providers (graceful fallback)
  *
+ * By default, returns a simplified response with only essential fields.
+ * Use the `extended` option to get full provider details including domains and alias configuration.
+ *
  * @param email - The email address to analyze
- * @param timeout - Optional timeout for DNS queries in milliseconds (default: 5000ms)
- * @returns Promise resolving to EmailProviderResult with provider info and error context
+ * @param options - Optional configuration: timeout for DNS queries (default: 5000ms) and extended response flag
+ * @returns Promise resolving to SimplifiedEmailProviderResult (default) or EmailProviderResult (if extended)
  *
  * @example
  * ```typescript
- * // Consumer email
- * const result = await getEmailProvider('local@domain.tld');
- * console.log(result.provider?.companyProvider); // Provider name
- * console.log(result.loginUrl);                  // Login URL
+ * // Default: Simplified response (recommended for frontend)
+ * const result = await getEmailProvider('user@gmail.com');
+ * // Returns: { provider: { companyProvider, loginUrl, type }, email, loginUrl, detectionMethod }
+ *
+ * // Extended response (includes domains, alias config, etc.)
+ * const extended = await getEmailProvider('user@gmail.com', { extended: true });
+ * // Returns: { provider: { companyProvider, loginUrl, domains, alias, type, ... }, ... }
  *
  * // Business domain
  * const business = await getEmailProvider('local@business.tld');
@@ -112,21 +129,34 @@ function validateAndParseEmailForLookup(email) {
  * console.log(invalid.error?.message); // "Invalid email format"
  * ```
  */
-async function getEmailProvider(email, timeout) {
+async function getEmailProvider(email, options) {
+    // Parse options - support both legacy (number) and new (object) format
+    const timeout = typeof options === 'number' ? options : options?.timeout;
+    const extended = typeof options === 'object' && options?.extended === true;
     try {
         const parsed = validateAndParseEmailForLookup(email);
         if (!parsed.ok) {
-            return {
+            // 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
+            }
+            const errorResult = {
                 provider: null,
-                email: parsed.email,
-                loginUrl: null,
+                email: normalizedEmail,
+                ...(extended ? { loginUrl: null } : {}),
                 error: parsed.error
             };
+            return extended ? errorResult : errorResult;
         }
         const domain = parsed.domain;
         // First try synchronous domain matching
-        const syncResult = getEmailProviderSync(email);
+        const syncResult = getEmailProviderSync(email, { extended });
         if (syncResult.provider) {
+            // Email is already normalized in getEmailProviderSync
             return {
                 ...syncResult,
                 detectionMethod: 'domain_match'
@@ -135,15 +165,16 @@ async function getEmailProvider(email, timeout) {
         // Fall back to DNS detection for business domains
         const loadResult = (0, provider_loader_1.loadProviders)();
         if (!loadResult.success) {
-            return {
+            const errorResult = {
                 provider: null,
                 email,
-                loginUrl: null,
+                ...(extended ? { loginUrl: null } : {}),
                 error: {
                     type: 'NETWORK_ERROR',
                     message: 'Service temporarily unavailable'
                 }
             };
+            return extended ? errorResult : errorResult;
         }
         const providers = loadResult.providers;
         const concurrentResult = await (0, concurrent_dns_1.detectProviderConcurrent)(domain, providers, {
@@ -151,17 +182,42 @@ 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
+        }
+        if (extended) {
+            const result = {
+                provider: concurrentResult.provider,
+                email: normalizedEmail,
+                loginUrl: concurrentResult.provider?.loginUrl || null,
+                detectionMethod: concurrentResult.detectionMethod || 'mx_record'
+            };
+            if (concurrentResult.proxyService) {
+                result.proxyService = concurrentResult.proxyService;
+            }
+            // Add error context for null results
+            if (!result.provider && !result.proxyService) {
+                result.error = {
+                    type: 'UNKNOWN_DOMAIN',
+                    message: `No email provider found for domain: ${domain}`
+                };
+            }
+            return result;
+        }
+        // Default: simplified response
         const result = {
-            provider: concurrentResult.provider,
-            email,
-            loginUrl: concurrentResult.provider?.loginUrl || null,
+            provider: simplifyProvider(concurrentResult.provider),
+            email: normalizedEmail,
             detectionMethod: concurrentResult.detectionMethod || 'mx_record'
         };
-        if (concurrentResult.proxyService) {
-            result.proxyService = concurrentResult.proxyService;
-        }
         // Add error context for null results
-        if (!result.provider && !result.proxyService) {
+        if (!result.provider) {
             result.error = {
                 type: 'UNKNOWN_DOMAIN',
                 message: `No email provider found for domain: ${domain}`
@@ -171,40 +227,36 @@ async function getEmailProvider(email, timeout) {
     }
     catch (error) {
         // Enhanced error handling
+        const errorResult = {
+            provider: null,
+            email,
+            error: {}
+        };
+        if (extended) {
+            errorResult.loginUrl = null;
+        }
         if (error instanceof Error && error.message.includes('Rate limit exceeded')) {
             const retryMatch = error.message.match(/Try again in (\d+) seconds/);
             const retryAfter = retryMatch?.[1] ? parseInt(retryMatch[1], 10) : undefined;
-            return {
-                provider: null,
-                email,
-                loginUrl: null,
-                error: {
-                    type: 'RATE_LIMITED',
-                    message: 'DNS query rate limit exceeded',
-                    ...(retryAfter !== undefined ? { retryAfter } : {})
-                }
+            errorResult.error = {
+                type: 'RATE_LIMITED',
+                message: 'DNS query rate limit exceeded',
+                ...(retryAfter !== undefined ? { retryAfter } : {})
             };
+            return extended ? errorResult : errorResult;
         }
         if (error instanceof Error && error.message.includes('timeout')) {
-            return {
-                provider: null,
-                email,
-                loginUrl: null,
-                error: {
-                    type: 'DNS_TIMEOUT',
-                    message: `DNS lookup timed out after ${timeout || 5000}ms`
-                }
+            errorResult.error = {
+                type: 'DNS_TIMEOUT',
+                message: `DNS lookup timed out after ${timeout || 5000}ms`
             };
+            return extended ? errorResult : errorResult;
         }
-        return {
-            provider: null,
-            email,
-            loginUrl: null,
-            error: {
-                type: 'NETWORK_ERROR',
-                message: error instanceof Error ? error.message : 'Unknown network error'
-            }
+        errorResult.error = {
+            type: 'NETWORK_ERROR',
+            message: error instanceof Error ? error.message : 'Unknown network error'
         };
+        return extended ? errorResult : errorResult;
     }
 }
 /**
@@ -213,14 +265,22 @@ async function getEmailProvider(email, timeout) {
  * This function only checks predefined domains and returns immediately.
  * Use this when you can't use async functions or don't want DNS lookups.
  *
+ * By default, returns a simplified response with only essential fields.
+ * Use the `extended` option to get full provider details including domains and alias configuration.
+ *
  * @param email - The email address to analyze
- * @returns EmailProviderResult with provider info (limited to known domains)
+ * @param options - Optional configuration: extended response flag
+ * @returns SimplifiedEmailProviderResult (default) or EmailProviderResult (if extended) with provider info (limited to known domains)
  *
  * @example
  * ```typescript
- * // Works for known domains
+ * // Default: Simplified response (recommended for frontend)
  * const gmail = getEmailProviderSync('user@gmail.com');
- * console.log(gmail.provider?.companyProvider); // "Gmail"
+ * // Returns: { provider: { companyProvider, loginUrl, type }, email, loginUrl }
+ *
+ * // Extended response (includes domains, alias config, etc.)
+ * const extended = getEmailProviderSync('user@gmail.com', { extended: true });
+ * // Returns: { provider: { companyProvider, loginUrl, domains, alias, type, ... }, ... }
  *
  * // Unknown domains return null
  * const unknown = getEmailProviderSync('user@mycompany.com');
@@ -228,16 +288,28 @@ async function getEmailProvider(email, timeout) {
  * console.log(unknown.error?.type); // "UNKNOWN_DOMAIN"
  * ```
  */
-function getEmailProviderSync(email) {
+function getEmailProviderSync(email, options) {
+    const extended = options?.extended === true;
     try {
         const parsed = validateAndParseEmailForLookup(email);
         if (!parsed.ok) {
-            return {
+            // 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
+            }
+            const errorResult = {
                 provider: null,
-                email: parsed.email,
-                loginUrl: null,
+                email: normalizedEmail,
                 error: parsed.error
             };
+            if (extended) {
+                errorResult.loginUrl = null;
+            }
+            return extended ? errorResult : errorResult;
         }
         const domain = parsed.domain;
         // Load providers with verification
@@ -249,15 +321,18 @@ function getEmailProviderSync(email) {
                 if (process.env.NODE_ENV !== 'test' && !process.env.JEST_WORKER_ID) {
                     console.error('🚨 Provider lookup blocked due to validation failure');
                 }
-                return {
+                const errorResult = {
                     provider: null,
                     email,
-                    loginUrl: null,
                     error: {
                         type: 'NETWORK_ERROR',
                         message: 'Service temporarily unavailable'
                     }
                 };
+                if (extended) {
+                    errorResult.loginUrl = null;
+                }
+                return extended ? errorResult : errorResult;
             }
             const domainMap = getDomainMapFromProviders(result.providers);
             provider = domainMap.get(domain) || null;
@@ -266,20 +341,48 @@ function getEmailProviderSync(email) {
             if (process.env.NODE_ENV !== 'test' && !process.env.JEST_WORKER_ID) {
                 console.error('🚨 Provider lookup failed:', error);
             }
-            return {
+            const errorResult = {
                 provider: null,
                 email,
-                loginUrl: null,
                 error: {
                     type: 'NETWORK_ERROR',
                     message: 'Service temporarily unavailable'
                 }
             };
+            if (extended) {
+                errorResult.loginUrl = null;
+            }
+            return extended ? errorResult : errorResult;
         }
+        // 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
+        }
+        if (extended) {
+            const result = {
+                provider: provider || null,
+                email: normalizedEmail,
+                loginUrl: provider?.loginUrl || null,
+                detectionMethod: 'domain_match'
+            };
+            // Add error context for null results
+            if (!result.provider) {
+                result.error = {
+                    type: 'UNKNOWN_DOMAIN',
+                    message: `No email provider found for domain: ${domain} (sync mode - business domains not supported)`
+                };
+            }
+            return result;
+        }
+        // Default: simplified response
         const result = {
-            provider: provider || null,
-            email,
-            loginUrl: provider?.loginUrl || null,
+            provider: simplifyProvider(provider),
+            email: normalizedEmail,
             detectionMethod: 'domain_match'
         };
         // Add error context for null results
@@ -292,129 +395,56 @@ function getEmailProviderSync(email) {
         return result;
     }
     catch (error) {
-        return {
+        const errorResult = {
             provider: null,
             email,
-            loginUrl: null,
             error: {
                 type: 'INVALID_EMAIL',
                 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 = (0, idn_1.domainToPunycode)(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
+        if (extended) {
+            errorResult.loginUrl = null;
         }
-        const domainMap = getDomainMapFromProviders(result.providers);
-        provider = domainMap.get(domainPart) || null;
-    }
-    catch (error) {
-        return lowercaseEmail; // Return as-is if error occurs
+        return extended ? errorResult : errorResult;
     }
-    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.
  *
+ * By default, returns a simplified response with only essential fields.
+ * Use the `extended` option to get full provider details including domains and alias configuration.
+ *
  * @param email - The email address to analyze
  * @param options - Configuration options for DNS detection
- * @returns Promise resolving to EmailProviderResult with enhanced performance data
+ * @returns Promise resolving to SimplifiedEmailProviderResult (default) or EmailProviderResult (if extended) with enhanced performance data
  *
  * @example
  * ```typescript
- * // High-performance detection with concurrent DNS
+ * // Default: Simplified response with performance data
  * const result = await getEmailProviderFast('user@mycompany.com', {
  *   enableParallel: true,
  *   collectDebugInfo: true
  * });
+ * // Returns: { provider: { companyProvider, loginUrl, type }, email, loginUrl, detectionMethod, timing, confidence }
  *
- * console.log(result.provider?.companyProvider); // "Google Workspace"
- * console.log(result.detectionMethod);           // "mx_record"
- * console.log(result.timing);                    // { mx: 120, txt: 95, total: 125 }
+ * // Extended response (includes domains, alias config, etc.)
+ * const extended = await getEmailProviderFast('user@mycompany.com', {
+ *   enableParallel: true,
+ *   extended: true
+ * });
+ * console.log(extended.provider?.companyProvider); // "Google Workspace"
+ * console.log(extended.detectionMethod);           // "mx_record"
+ * console.log(extended.timing);                    // { mx: 120, txt: 95, total: 125 }
  * ```
  */
 async function getEmailProviderFast(email, options = {}) {
-    const { timeout = 5000, enableParallel = true, collectDebugInfo = false } = options;
+    const { timeout = 5000, enableParallel = true, collectDebugInfo = false, extended = false } = options;
     try {
         const parsed = validateAndParseEmailForLookup(email);
         if (!parsed.ok) {
@@ -428,8 +458,9 @@ async function getEmailProviderFast(email, options = {}) {
         const domain = parsed.domain;
         const trimmedEmail = parsed.trimmedEmail;
         // First try standard domain matching (fast path)
-        const syncResult = getEmailProviderSync(trimmedEmail);
+        const syncResult = getEmailProviderSync(trimmedEmail, { extended });
         if (syncResult.provider) {
+            // Email is already normalized in getEmailProviderSync
             return {
                 ...syncResult,
                 detectionMethod: 'domain_match',
@@ -456,34 +487,62 @@ 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
+        }
+        if (extended) {
+            const fastResult = {
+                provider: concurrentResult.provider,
+                email: normalizedEmail,
+                loginUrl: concurrentResult.provider?.loginUrl || null,
+                detectionMethod: concurrentResult.detectionMethod || 'mx_record',
+                timing: concurrentResult.timing,
+                confidence: concurrentResult.confidence,
+                debug: concurrentResult.debug,
+                error: !concurrentResult.provider && !concurrentResult.proxyService ? {
+                    type: 'UNKNOWN_DOMAIN',
+                    message: `No email provider found for domain: ${domain}`
+                } : undefined
+            };
+            if (concurrentResult.proxyService) {
+                fastResult.proxyService = concurrentResult.proxyService;
+            }
+            return fastResult;
+        }
+        // Default: simplified response
         const fastResult = {
-            provider: concurrentResult.provider,
-            email: trimmedEmail,
-            loginUrl: concurrentResult.provider?.loginUrl || null,
+            provider: simplifyProvider(concurrentResult.provider),
+            email: normalizedEmail,
             detectionMethod: concurrentResult.detectionMethod || 'mx_record',
             timing: concurrentResult.timing,
             confidence: concurrentResult.confidence,
             debug: concurrentResult.debug,
-            error: !concurrentResult.provider && !concurrentResult.proxyService ? {
+            error: !concurrentResult.provider ? {
                 type: 'UNKNOWN_DOMAIN',
                 message: `No email provider found for domain: ${domain}`
             } : undefined
         };
-        if (concurrentResult.proxyService) {
-            fastResult.proxyService = concurrentResult.proxyService;
-        }
         return fastResult;
     }
     catch (error) {
-        return {
+        const errorResult = {
             provider: null,
             email,
-            loginUrl: null,
             error: {
                 type: 'NETWORK_ERROR',
                 message: error instanceof Error ? error.message : 'DNS detection failed'
             }
         };
+        if (extended) {
+            errorResult.loginUrl = null;
+        }
+        return errorResult;
     }
 }
 /**

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