@mikkelscheike/email-provider-links 1.7.0 → 1.8.0

package/dist/index.d.ts

@@ -1,374 +1,66 @@
 /**
  * Email Provider Links
  *
- * A TypeScript package that provides direct links to email providers
- * based on email addresses to streamline login and password reset flows.
- *
- * The package uses a two-tier detection system:
- * 1. Fast domain lookup against a JSON database of known providers
- * 2. DNS-based detection for custom business domains using MX/TXT record analysis
- *
- * @packageDocumentation
- */
-/**
- * Simple rate limiter to prevent excessive DNS queries.
- * Tracks request timestamps and enforces a maximum number of requests per time window.
+ * A clean, modern email provider detection library with:
+ * - 93+ verified email providers covering 180+ domains
+ * - Concurrent DNS detection for business domains
+ * - Zero runtime dependencies
+ * - Comprehensive error handling
+ * - Email alias normalization
+ *
+ * @author Email Provider Links Team
+ * @license MIT
  */
-declare class SimpleRateLimiter {
-    private maxRequests;
-    private windowMs;
-    private requestTimestamps;
-    constructor(maxRequests?: number, windowMs?: number);
-    /**
-     * Checks if a request is allowed under the current rate limit.
-     * @returns true if request is allowed, false if rate limited
-     */
-    isAllowed(): boolean;
-    /**
-     * Gets the current number of requests in the window.
-     */
-    getCurrentCount(): number;
-    /**
-     * Gets the time until the rate limit resets (when oldest request expires).
-     * @returns milliseconds until reset, or 0 if not rate limited
-     */
-    getTimeUntilReset(): number;
-}
+export { getEmailProvider, getEmailProviderSync, getEmailProviderFast, normalizeEmail, emailsMatch, Config } from './api';
+export type { EmailProvider, EmailProviderResult } from './api';
+export { loadProviders } from './loader';
+export { detectProviderConcurrent } from './concurrent-dns';
+export type { ConcurrentDNSConfig, ConcurrentDNSResult } from './concurrent-dns';
+import { getEmailProvider, getEmailProviderSync, getEmailProviderFast, normalizeEmail, emailsMatch } from './api';
 /**
- * Represents an email provider with its associated domains and login URL.
- *
- * @interface EmailProvider
- * @example
- * ```typescript
- * {
- *   companyProvider: "Gmail",
- *   loginUrl: "https://mail.google.com/mail/",
- *   domains: ["gmail.com", "googlemail.com"],
- *   customDomainDetection: {
- *     mxPatterns: ["aspmx.l.google.com"],
- *     txtPatterns: ["v=spf1 include:_spf.google.com"]
- *   }
- * }
- * ```
+ * Get list of all supported email providers
+ * @returns Array of all email providers in the database
  */
-export interface EmailProvider {
-    /** Human-readable name of the email provider company */
-    companyProvider: string;
-    /** Direct URL to the provider's login/webmail page */
-    loginUrl: string;
-    /** Array of email domains this provider handles (e.g., ['gmail.com', 'googlemail.com']) */
-    domains: string[];
-    /** Optional DNS-based detection patterns for custom business domains */
-    customDomainDetection?: {
-        /** MX record patterns to match against (e.g., ['aspmx.l.google.com']) */
-        mxPatterns?: string[];
-        /** TXT record patterns to match against (e.g., ['v=spf1 include:_spf.google.com']) */
-        txtPatterns?: string[];
-    };
-}
+export declare function getSupportedProviders(): import("./api").EmailProvider[];
 /**
- * Result object returned by email provider detection functions.
- *
- * @interface EmailProviderResult
- * @example
- * ```typescript
- * {
- *   provider: { companyProvider: "Gmail", loginUrl: "https://mail.google.com/mail/", domains: ["gmail.com"] },
- *   email: "user@gmail.com",
- *   loginUrl: "https://mail.google.com/mail/",
- *   detectionMethod: "domain_match"
- * }
- * ```
- */
-export interface EmailProviderResult {
-    /** The detected email provider, or null if not found/behind proxy */
-    provider: EmailProvider | null;
-    /** The original email address that was analyzed */
-    email: string;
-    /** Direct URL to the email provider's login page, or null if unknown */
-    loginUrl: string | null;
-    /** Method used to detect the provider */
-    detectionMethod?: 'domain_match' | 'mx_record' | 'txt_record' | 'proxy_detected';
-    /** If a proxy service was detected, which service (e.g., 'Cloudflare') */
-    proxyService?: string;
-}
-/**
- * Result object returned by DNS-based provider detection.
- *
- * @interface DNSDetectionResult
- * @example
- * ```typescript
- * {
- *   provider: { companyProvider: "Google Workspace", ... },
- *   detectionMethod: "mx_record",
- *   proxyService: undefined
- * }
- * ```
- */
-export interface DNSDetectionResult {
-    /** The detected email provider, or null if not found/behind proxy */
-    provider: EmailProvider | null;
-    /** Method used for DNS-based detection */
-    detectionMethod: 'mx_record' | 'txt_record' | 'proxy_detected' | null;
-    /** If a proxy service was detected, which service (e.g., 'Cloudflare') */
-    proxyService?: string;
-}
-/**
- * Validates if a string is a valid email address using a basic regex pattern.
- *
- * @param email - The string to validate as an email address
- * @returns true if the string matches basic email format, false otherwise
- *
- * @example
- * ```typescript
- * isValidEmail('user@gmail.com');     // true
- * isValidEmail('invalid-email');      // false
- * isValidEmail('user@domain');        // false
- * ```
- *
- * @remarks
- * This uses a simple regex pattern that covers most common email formats.
- * It may not catch all edge cases defined in RFC 5322, but works for
- * standard email addresses.
+ * Check if an email provider is supported
+ * @param email - Email address to check
+ * @returns true if the provider is supported
  */
-export declare function isValidEmail(email: string): boolean;
+export declare function isEmailProviderSupported(email: string): boolean;
 /**
- * Extracts the domain portion from an email address.
- *
- * @param email - The email address to extract the domain from
- * @returns The domain in lowercase, or null if the email is invalid
- *
- * @example
- * ```typescript
- * extractDomain('user@Gmail.com');    // 'gmail.com'
- * extractDomain('test@yahoo.co.uk');  // 'yahoo.co.uk'
- * extractDomain('invalid-email');     // null
- * ```
- *
- * @remarks
- * The domain is automatically normalized to lowercase for consistent matching.
+ * Extract domain from email address
+ * @param email - Email address
+ * @returns Domain portion or null if invalid
  */
 export declare function extractDomain(email: string): string | null;
 /**
- * Finds an email provider by matching the domain against the known providers database.
- * Uses an optimized Map for O(1) lookup performance.
- *
- * @param domain - The email domain to look up (e.g., 'gmail.com')
- * @returns The matching EmailProvider object, or null if not found
- *
- * @example
- * ```typescript
- * const provider = findEmailProvider('gmail.com');
- * console.log(provider?.companyProvider); // 'Gmail'
- * console.log(provider?.loginUrl);        // 'https://mail.google.com/mail/'
- * ```
- *
- * @remarks
- * This function performs a case-insensitive O(1) lookup using a pre-built Map.
- * It only checks the predefined JSON database, not DNS records.
- * Performance optimized from O(n*m) to O(1) where n=providers, m=domains per provider.
+ * Validate email format
+ * @param email - Email address to validate
+ * @returns true if valid format
  */
-export declare function findEmailProvider(domain: string): EmailProvider | null;
-/**
- * Gets email provider information and login URL for a given email address.
- * This is the basic/synchronous version that only checks predefined domains.
- *
- * @param email - The email address to analyze
- * @returns EmailProviderResult containing provider info and login URL
- *
- * @example
- * ```typescript
- * const result = getEmailProviderLink('user@gmail.com');
- * console.log(result.loginUrl);        // 'https://mail.google.com/mail/'
- * console.log(result.provider?.companyProvider); // 'Gmail'
- * ```
- *
- * @remarks
- * This function only checks against the predefined JSON database of known domains.
- * It will NOT detect business domains that use major email providers (e.g.,
- * mycompany.com using Google Workspace). For comprehensive detection including
- * business domains, use {@link getEmailProviderLinkWithDNS} instead.
- *
- * **Limitations:**
- * - Only synchronous operation (no DNS lookups)
- * - Limited to domains in the JSON database
- * - Won't detect custom business domains
- * - No proxy service detection
- */
-export declare function getEmailProviderLink(email: string): EmailProviderResult;
-/**
- * Returns an array of all supported email providers.
- *
- * @returns A copy of the EMAIL_PROVIDERS array
- *
- * @example
- * ```typescript
- * const providers = getSupportedProviders();
- * console.log(providers.length);  // 55+
- * console.log(providers[0].companyProvider); // 'Gmail'
- * ```
- *
- * @remarks
- * Returns a shallow copy to prevent external modification of the internal
- * providers array. The returned array includes both consumer email providers
- * (gmail.com, yahoo.com) and business email providers with DNS detection patterns.
- */
-export declare function getSupportedProviders(): EmailProvider[];
-/**
- * Checks if an email address uses a supported email provider.
- *
- * @param email - The email address to check
- * @returns true if the provider is supported, false otherwise
- *
- * @example
- * ```typescript
- * isEmailProviderSupported('user@gmail.com');     // true
- * isEmailProviderSupported('user@unknown.com');   // false
- * ```
- *
- * @remarks
- * This is a convenience function that uses {@link getEmailProviderLink} internally.
- * It only checks predefined domains, not DNS-based detection. For business
- * domain support checking, you would need to use {@link getEmailProviderLinkWithDNS}.
- */
-export declare function isEmailProviderSupported(email: string): boolean;
-/**
- * Performs DNS-based detection for custom business domains using MX and TXT record analysis.
- * This function is used internally by {@link getEmailProviderLinkWithDNS} but can also be
- * called directly to analyze domain email configuration.
- *
- * @param domain - The domain to analyze (e.g., 'mycompany.com')
- * @param timeoutMs - Optional timeout for DNS queries in milliseconds (default: 5000ms)
- * @returns Promise resolving to DNSDetectionResult with provider info or proxy detection
- *
- * @example
- * ```typescript
- * const result = await detectProviderByDNS('microsoft.com');
- * console.log(result.provider?.companyProvider); // 'Microsoft 365 (Business)'
- * console.log(result.detectionMethod);           // 'mx_record'
- * ```
- *
- * @remarks
- * **Detection Algorithm:**
- * 1. Checks rate limiting (max 10 requests per minute)
- * 2. Performs MX record lookup for the domain
- * 3. Checks if MX records match known proxy services (Cloudflare, etc.)
- * 4. If proxy detected, returns null provider with proxy info
- * 5. Otherwise, matches MX records against business email provider patterns
- * 6. If no MX match, falls back to TXT record analysis (SPF records, etc.)
- * 7. Returns the first matching provider or null if none found
- *
- * **Rate Limiting:**
- * - Maximum 10 DNS requests per 60-second window
- * - Rate limit exceeded returns error with retry information
- * - Prevents abuse and excessive DNS queries
- *
- * **Provider Patterns Checked:**
- * - Google Workspace: aspmx.l.google.com, aspmx2.googlemail.com, etc.
- * - Microsoft 365: *.protection.outlook.com, *.outlook.com
- * - ProtonMail: mail.protonmail.ch, mailsec.protonmail.ch
- * - FastMail: *.messagingengine.com
- * - And many others...
- *
- * **Error Handling:**
- * DNS lookup failures are caught and the function gracefully falls back
- * to the next detection method or returns null if all methods fail.
- */
-export declare function detectProviderByDNS(domain: string, timeoutMs?: number): Promise<DNSDetectionResult>;
+export declare function isValidEmail(email: string): boolean;
 /**
- * Enhanced email provider detection with automatic DNS-based custom domain detection.
- * This is the recommended function for most use cases as it provides comprehensive
- * detection coverage including business domains and proxy services.
- *
- * @param email - The email address to analyze
- * @param timeoutMs - Optional timeout for DNS queries in milliseconds (default: 5000ms)
- * @returns Promise resolving to EmailProviderResult with provider info and detection method
- *
- * @example
- * ```typescript
- * // Consumer email (fast domain match)
- * const gmail = await getEmailProviderLinkWithDNS('user@gmail.com');
- * console.log(gmail.provider?.companyProvider); // 'Gmail'
- * console.log(gmail.detectionMethod);           // 'domain_match'
- *
- * // Business domain (DNS detection)
- * const business = await getEmailProviderLinkWithDNS('user@mycompany.com');
- * console.log(business.provider?.companyProvider); // 'Google Workspace' (if detected)
- * console.log(business.detectionMethod);           // 'mx_record'
- *
- * // Proxied domain (proxy detection)
- * const proxied = await getEmailProviderLinkWithDNS('user@proxied-domain.com');
- * console.log(proxied.provider);         // null
- * console.log(proxied.proxyService);     // 'Cloudflare'
- * console.log(proxied.detectionMethod);  // 'proxy_detected'
- * ```
- *
- * @remarks
- * **Detection Hierarchy (in order):**
- * 1. **Domain Match**: Fast lookup against predefined domains (gmail.com, yahoo.com, etc.)
- * 2. **DNS MX Records**: Analyzes mail exchange records for business email providers
- * 3. **DNS TXT Records**: Checks SPF and verification records as fallback
- * 4. **Proxy Detection**: Identifies when domains are behind CDN/proxy services
- *
- * **Supported Detection Cases:**
- * - ✅ Consumer emails: gmail.com, yahoo.com, outlook.com, etc.
- * - ✅ Business domains: Google Workspace, Microsoft 365, ProtonMail Business, etc.
- * - ✅ Proxy services: Cloudflare, CloudFront, Fastly, etc.
- * - ✅ International providers: QQ Mail, NetEase, Yandex, etc.
- *
- * **Performance:**
- * - Fast for known consumer domains (synchronous JSON lookup)
- * - Additional DNS lookup time for unknown domains (~100-500ms)
- * - Graceful degradation if DNS lookups fail
- *
- * **Error Handling:**
- * - Invalid email addresses return null provider
- * - DNS lookup failures are caught and don't throw errors
- * - Network timeouts gracefully fall back to null detection
- *
- * **Use Cases:**
- * - Password reset flows ("Check your Gmail inbox")
- * - Login form enhancements (direct links to email providers)
- * - Email client detection for support purposes
- * - Business domain analysis for enterprise features
+ * Library metadata
  */
-export declare function getEmailProviderLinkWithDNS(email: string, timeoutMs?: number): Promise<EmailProviderResult>;
+export declare const PROVIDER_COUNT = 93;
+export declare const DOMAIN_COUNT = 178;
 /**
- * Rate limiting configuration constants and utilities.
- * @public
+ * Default export for convenience
  */
-export declare const RateLimit: {
-    MAX_REQUESTS: number;
-    WINDOW_MS: number;
-    SimpleRateLimiter: typeof SimpleRateLimiter;
-    /**
-     * Gets the current rate limiter instance for inspection or testing.
-     * @internal
-     */
-    getCurrentLimiter: () => SimpleRateLimiter;
-};
-export * from './alias-detection';
-export * from './security/url-validator';
-export * from './security/hash-verifier';
-export * from './security/secure-loader';
 declare const _default: {
-    getEmailProviderLink: typeof getEmailProviderLink;
-    getEmailProviderLinkWithDNS: typeof getEmailProviderLinkWithDNS;
-    detectProviderByDNS: typeof detectProviderByDNS;
-    isValidEmail: typeof isValidEmail;
-    extractDomain: typeof extractDomain;
-    findEmailProvider: typeof findEmailProvider;
-    getSupportedProviders: typeof getSupportedProviders;
-    isEmailProviderSupported: typeof isEmailProviderSupported;
-    RateLimit: {
-        MAX_REQUESTS: number;
-        WINDOW_MS: number;
-        SimpleRateLimiter: typeof SimpleRateLimiter;
-        /**
-         * Gets the current rate limiter instance for inspection or testing.
-         * @internal
-         */
-        getCurrentLimiter: () => SimpleRateLimiter;
+    getEmailProvider: typeof getEmailProvider;
+    getEmailProviderSync: typeof getEmailProviderSync;
+    getEmailProviderFast: typeof getEmailProviderFast;
+    normalizeEmail: typeof normalizeEmail;
+    emailsMatch: typeof emailsMatch;
+    Config: {
+        readonly DEFAULT_DNS_TIMEOUT: 5000;
+        readonly MAX_DNS_REQUESTS_PER_MINUTE: 10;
+        readonly SUPPORTED_PROVIDERS_COUNT: 93;
+        readonly SUPPORTED_DOMAINS_COUNT: 180;
     };
+    PROVIDER_COUNT: number;
+    DOMAIN_COUNT: number;
 };
 export default _default;