@mikkelscheike/email-provider-links 5.1.0 → 5.1.1

package/README.md

@@ -100,41 +100,85 @@ Fully compatible with the latest Node.js 24.x and 25.x! The library is tested on
 
 ### Core Functions
 
-#### `getEmailProvider(email, timeout?)`
+#### `getEmailProvider(email, options?)`
 **Recommended** - Complete provider detection with business domain support.
 
 **✨ Automatic Email Normalization**: The returned `email` field is automatically normalized using provider-specific alias rules. For example, `user+tag@gmail.com` returns `user@gmail.com` in the result.
 
+**📦 Simplified Response (Default)**: By default, returns only essential fields for frontend use. Use `{ extended: true }` to get full provider details including domains array and alias configuration.
+
 Error notes:
 - `INVALID_EMAIL` is returned for common malformed inputs (e.g. missing `@`, missing TLD).
 - `IDN_VALIDATION_ERROR` is reserved for true encoding issues.
 
 ```typescript
-// Known providers (instant response)
+// Default: Simplified response (recommended for frontend)
 const result1 = await getEmailProvider('user@gmail.com');
-// Returns: { provider: "Gmail", email: "user@gmail.com", loginUrl: "https://mail.google.com/mail/" }
+// Returns: {
+//   provider: { companyProvider: "Gmail", loginUrl: "https://mail.google.com/mail/", type: "public_provider" },
+//   email: "user@gmail.com",
+//   detectionMethod: "domain_match"
+// }
 
 // Email normalization is automatic
 const result2 = await getEmailProvider('user+tag@gmail.com');
-// Returns: { provider: "Gmail", email: "user@gmail.com", loginUrl: "https://mail.google.com/mail/" }
+// Returns: {
+//   provider: { companyProvider: "Gmail", loginUrl: "https://mail.google.com/mail/", type: "public_provider" },
+//   email: "user@gmail.com",  // Normalized
+//   detectionMethod: "domain_match"
+// }
+
+// Extended response (includes domains, alias config, etc.)
+const extended = await getEmailProvider('user@gmail.com', { extended: true });
+// Returns: {
+//   provider: {
+//     companyProvider: "Gmail",
+//     loginUrl: "https://mail.google.com/mail/",
+//     domains: ["gmail.com", "googlemail.com"],  // Only in extended
+//     alias: { dots: { ignore: true, strip: false }, ... },  // Only in extended
+//     type: "public_provider"
+//   },
+//   email: "user@gmail.com",
+//   loginUrl: "https://mail.google.com/mail/",  // Top-level loginUrl only in extended
+//   detectionMethod: "domain_match"
+// }
 
 // Business domains (DNS lookup with timeout)
-const result3 = await getEmailProvider('user@company.com', 2000);
-// Returns: { provider: "Google Workspace", email: "user@company.com", detectionMethod: "mx_record" }
+const result3 = await getEmailProvider('user@company.com', { timeout: 2000 });
+// Returns: {
+//   provider: { companyProvider: "Google Workspace", loginUrl: "...", type: "custom_provider" },
+//   email: "user@company.com",
+//   detectionMethod: "mx_record"
+// }
 ```
 
-#### `getEmailProviderSync(email)`
+#### `getEmailProviderSync(email, options?)`
 **Fast** - Instant checks for known providers (no DNS lookup).
 
 **✨ Automatic Email Normalization**: The returned `email` field is automatically normalized using provider-specific alias rules.
 
+**📦 Simplified Response (Default)**: By default, returns only essential fields. Use `{ extended: true }` to get full provider details.
+
 ```typescript
+// Default: Simplified response
 const result = getEmailProviderSync('user@outlook.com');
-// Returns: { provider: "Outlook", email: "user@outlook.com", loginUrl: "https://outlook.live.com/" }
+// Returns: {
+//   provider: { companyProvider: "Outlook", loginUrl: "https://outlook.live.com/", type: "public_provider" },
+//   email: "user@outlook.com",
+//   detectionMethod: "domain_match"
+// }
 
 // Email normalization is automatic
 const result2 = getEmailProviderSync('u.s.e.r+tag@gmail.com');
-// Returns: { provider: "Gmail", email: "user@gmail.com", loginUrl: "https://mail.google.com/mail/" }
+// Returns: {
+//   provider: { companyProvider: "Gmail", loginUrl: "https://mail.google.com/mail/", type: "public_provider" },
+//   email: "user@gmail.com",  // Normalized
+//   detectionMethod: "domain_match"
+// }
+
+// Extended response (includes domains, alias config, etc.)
+const extended = getEmailProviderSync('user@gmail.com', { extended: true });
+// Returns full provider object with domains array and alias configuration
 ```
 
 ### Email Alias Support
@@ -171,24 +215,83 @@ async function handlePasswordReset(email: string) {
     throw new Error(`Invalid email: ${validation.error?.message}`);
   }
 
-  // Get provider information (email is automatically normalized in result)
+  // Get provider information (default: simplified response)
+  // Email is automatically normalized in result
   const result = await getEmailProvider(email);
   
   return {
-    providerUrl: result.loginUrl,
+    providerUrl: result.provider?.loginUrl || null,  // Access loginUrl from provider object
     providerName: result.provider?.companyProvider || null,
     normalizedEmail: result.email, // Already normalized (e.g., 'user@gmail.com' from 'user+tag@gmail.com')
     isSupported: result.provider !== null,
     detectionMethod: result.detectionMethod
   };
 }
+
+// If you need full provider details (domains, alias config, etc.)
+async function analyzeEmailProvider(email: string) {
+  const result = await getEmailProvider(email, { extended: true });
+  
+  // Access full provider details
+  if (result.provider) {
+    console.log('All domains:', result.provider.domains);
+    console.log('Alias rules:', result.provider.alias);
+  }
+  
+  return result;
+}
+```
+
+## Response Formats
+
+### Simplified Response (Default)
+The default response includes only essential fields needed by most applications:
+
+```typescript
+{
+  provider: {
+    companyProvider: "Gmail",           // Provider name
+    loginUrl: "https://mail.google.com/mail/",  // Login URL (access via provider.loginUrl)
+    type: "public_provider"              // Provider type
+  },
+  email: "user@gmail.com",             // Normalized email
+  detectionMethod: "domain_match"       // How provider was detected
+}
+```
+
+### Extended Response
+Use `{ extended: true }` to get full provider details including internal metadata:
+
+```typescript
+{
+  provider: {
+    companyProvider: "Gmail",
+    loginUrl: "https://mail.google.com/mail/",
+    domains: ["gmail.com", "googlemail.com"],  // All domains for this provider
+    alias: {                                   // Alias handling configuration
+      dots: { ignore: true, strip: false },
+      plus: { ignore: true, strip: true },
+      case: { ignore: true, strip: true }
+    },
+    type: "public_provider",
+    customDomainDetection: { ... }             // DNS detection patterns
+  },
+  email: "user@gmail.com",
+  loginUrl: "https://mail.google.com/mail/",
+  detectionMethod: "domain_match"
+}
 ```
 
+**When to use Extended**: Only use `{ extended: true }` if you need access to the `domains` array or `alias` configuration for custom email processing logic. For most frontend use cases, the default simplified response is sufficient and more efficient.
+
 ## Configuration
 
 ```typescript
 // Custom DNS timeout (default: 5000ms)
-const result = await getEmailProvider(email, 2000);
+const result = await getEmailProvider(email, { timeout: 2000 });
+
+// Extended response with custom timeout
+const extended = await getEmailProvider(email, { timeout: 2000, extended: true });
 
 // Rate limiting configuration
 import { Config } from '@mikkelscheike/email-provider-links';
@@ -215,7 +318,7 @@ console.log(`Total providers: ${providers.length}`);
 
 ### Email Alias Detection & Normalization
 
-**✨ Note**: `getEmailProvider()`, `getEmailProviderSync()`, and `getEmailProviderFast()` automatically normalize emails in their results. You can use `normalizeEmail()` directly when you only need normalization without provider detection.
+**✨ Note**: `getEmailProvider()`, `getEmailProviderSync()`, and `getEmailProviderFast()` automatically normalize emails in their results and return simplified responses by default (only essential fields). Use `{ extended: true }` to get full provider details. You can use `normalizeEmail()` directly when you only need normalization without provider detection.
 
 ```typescript
 import { 

package/dist/api.d.ts

@@ -30,7 +30,21 @@ export interface EmailProvider {
     };
 }
 /**
- * Enhanced result interface with rich error context
+ * Simplified provider information for frontend use
+ * Contains only essential fields needed by consumers
+ */
+export interface SimplifiedProvider {
+    /** The provider name (e.g., "Gmail", "ProtonMail") */
+    companyProvider: string;
+    /** Direct URL to the email provider's login page */
+    loginUrl: string | null;
+    /** Provider type for UI differentiation */
+    type: ProviderType;
+}
+/**
+ * Extended result interface with full provider details
+ * Includes internal implementation details like domains array and alias configuration.
+ * Use this when you need access to all provider metadata.
  */
 export interface EmailProviderResult {
     /** The detected email provider, or null if not found */
@@ -51,6 +65,26 @@ export interface EmailProviderResult {
         idnError?: string;
     };
 }
+/**
+ * Standard result interface (default)
+ * Contains only essential information needed by consumers.
+ * This is the default response format for all API functions.
+ */
+export interface SimplifiedEmailProviderResult {
+    /** The detected email provider (simplified), or null if not found */
+    provider: SimplifiedProvider | null;
+    /** The normalized email address */
+    email: string;
+    /** Method used to detect the provider */
+    detectionMethod?: 'domain_match' | 'mx_record' | 'txt_record' | 'both' | 'proxy_detected';
+    /** Error information if detection failed */
+    error?: {
+        type: 'INVALID_EMAIL' | 'DNS_TIMEOUT' | 'RATE_LIMITED' | 'UNKNOWN_DOMAIN' | 'NETWORK_ERROR' | 'IDN_VALIDATION_ERROR';
+        message: string;
+        retryAfter?: number;
+        idnError?: string;
+    };
+}
 /**
  * Get email provider information for any email address.
  *
@@ -59,16 +93,22 @@ export interface EmailProviderResult {
  * - 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');
@@ -81,21 +121,32 @@ export interface EmailProviderResult {
  * console.log(invalid.error?.message); // "Invalid email format"
  * ```
  */
-export declare function getEmailProvider(email: string, timeout?: number): Promise<EmailProviderResult>;
+export declare function getEmailProvider(email: string, options?: number | {
+    timeout?: number;
+    extended?: boolean;
+}): Promise<SimplifiedEmailProviderResult | EmailProviderResult>;
 /**
  * Get email provider information synchronously (no DNS lookup).
  *
  * 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');
@@ -103,34 +154,46 @@ export declare function getEmailProvider(email: string, timeout?: number): Promi
  * console.log(unknown.error?.type); // "UNKNOWN_DOMAIN"
  * ```
  */
-export declare function getEmailProviderSync(email: string): EmailProviderResult;
+export declare function getEmailProviderSync(email: string, options?: {
+    extended?: boolean;
+}): SimplifiedEmailProviderResult | EmailProviderResult;
 export { normalizeEmail, emailsMatch } from './alias-detection';
 /**
  * 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 }
  * ```
  */
 export declare function getEmailProviderFast(email: string, options?: {
     timeout?: number;
     enableParallel?: boolean;
     collectDebugInfo?: boolean;
-}): Promise<EmailProviderResult & {
+    extended?: boolean;
+}): Promise<(SimplifiedEmailProviderResult | EmailProviderResult) & {
     timing?: {
         mx: number;
         txt: number;

package/dist/api.js

@@ -81,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.
  *
@@ -89,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');
@@ -111,7 +129,10 @@ 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) {
@@ -123,16 +144,17 @@ async function getEmailProvider(email, timeout) {
             catch {
                 // If normalization fails, use original email
             }
-            return {
+            const errorResult = {
                 provider: null,
                 email: normalizedEmail,
-                loginUrl: null,
+                ...(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 {
@@ -143,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, {
@@ -168,17 +191,33 @@ async function getEmailProvider(email, timeout) {
         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,
+            provider: simplifyProvider(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) {
+        if (!result.provider) {
             result.error = {
                 type: 'UNKNOWN_DOMAIN',
                 message: `No email provider found for domain: ${domain}`
@@ -188,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;
     }
 }
 /**
@@ -230,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');
@@ -245,7 +288,8 @@ 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) {
@@ -257,12 +301,15 @@ function getEmailProviderSync(email) {
             catch {
                 // If normalization fails, use original email
             }
-            return {
+            const errorResult = {
                 provider: null,
                 email: normalizedEmail,
-                loginUrl: null,
                 error: parsed.error
             };
+            if (extended) {
+                errorResult.loginUrl = null;
+            }
+            return extended ? errorResult : errorResult;
         }
         const domain = parsed.domain;
         // Load providers with verification
@@ -274,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;
@@ -291,15 +341,18 @@ 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
@@ -310,10 +363,26 @@ function getEmailProviderSync(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,
+            provider: simplifyProvider(provider),
             email: normalizedEmail,
-            loginUrl: provider?.loginUrl || null,
             detectionMethod: 'domain_match'
         };
         // Add error context for null results
@@ -326,15 +395,18 @@ 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'
             }
         };
+        if (extended) {
+            errorResult.loginUrl = null;
+        }
+        return extended ? errorResult : errorResult;
     }
 }
 // Re-export alias detection functions from the dedicated module
@@ -345,25 +417,34 @@ Object.defineProperty(exports, "emailsMatch", { enumerable: true, get: function
  * 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) {
@@ -377,7 +458,7 @@ 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 {
@@ -415,34 +496,53 @@ async function getEmailProviderFast(email, options = {}) {
         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,
+            provider: simplifyProvider(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 ? {
+            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/hash-verifier.js

@@ -29,7 +29,7 @@ const KNOWN_GOOD_HASHES = {
     // SHA-256 hash of the legitimate emailproviders.json
     'emailproviders.json': 'a4fe056edad44ae5479cc100d5cc67cb5f6df86e19c4209db6c5f715f5bf070e',
     // You can add hashes for other critical files
-    'package.json': 'ea417a1548c59f3945ea727968c90a43d6a1e24f72c646ff708edd7da2dcc964',
+    'package.json': 'fc7bab75bddc7af13adce8cd3e51f67f597c999eea500bcdc983cd79b60b13c0',
 };
 /**
  * Calculates SHA-256 hash of a file or string content

package/dist/index.d.ts

@@ -20,7 +20,7 @@ import { getEmailProvider, getEmailProviderSync, getEmailProviderFast, normalize
 import { detectProviderConcurrent } from './concurrent-dns';
 import { validateInternationalEmail, emailToPunycode, domainToPunycode } from './idn';
 export { getEmailProvider, getEmailProviderSync, getEmailProviderFast, normalizeEmail, emailsMatch, detectEmailAlias, Config };
-export type { EmailProvider, EmailProviderResult } from './api';
+export type { EmailProvider, EmailProviderResult, SimplifiedProvider, SimplifiedEmailProviderResult } from './api';
 export type { AliasDetectionResult } from './alias-detection';
 export { loadProviders, detectProviderConcurrent, validateInternationalEmail, emailToPunycode, domainToPunycode };
 export type { ConcurrentDNSConfig, ConcurrentDNSResult } from './concurrent-dns';

package/dist/index.js

@@ -304,7 +304,7 @@ function batchProcessEmails(emails, options = {}) {
                 try {
                     const providerResult = (0, api_1.getEmailProviderSync)(validation.normalizedEmail);
                     result.provider = providerResult.provider?.companyProvider || null;
-                    result.loginUrl = providerResult.loginUrl;
+                    result.loginUrl = providerResult.provider?.loginUrl || null;
                 }
                 catch {
                     result.provider = null;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mikkelscheike/email-provider-links",
-  "version": "5.1.0",
+  "version": "5.1.1",
   "description": "TypeScript library for email provider detection with 130 providers (218 domains), concurrent DNS resolution, optimized performance, 94.65% test coverage, and enterprise security for login and password reset flows",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",