@mikkelscheike/email-provider-links
Version:
TypeScript library for email provider detection with 93 providers (207 domains), concurrent DNS resolution, optimized performance, 94.65% test coverage, and enterprise security for login and password reset flows
190 lines • 6.57 kB
TypeScript
/**
* Email Provider Links API
*
* Simplified API with better error handling and performance improvements.
* Clean function names and enhanced error context.
*/
export type ProviderType = 'public_provider' | 'custom_provider' | 'proxy_service';
export interface EmailProvider {
companyProvider: string;
loginUrl: string | null;
domains: string[];
type: ProviderType;
alias?: {
dots?: {
ignore: boolean;
strip: boolean;
};
plus?: {
ignore: boolean;
strip: boolean;
};
case?: {
ignore: boolean;
strip: boolean;
};
};
customDomainDetection?: {
mxPatterns?: string[];
txtPatterns?: string[];
};
}
/**
* Enhanced result interface with rich error context
*/
export interface EmailProviderResult {
/** The detected email provider, or null if not found */
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' | 'both' | 'proxy_detected';
/** If a proxy service was detected, which service (e.g., 'Cloudflare') */
proxyService?: string;
/** 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.
*
* This is the primary function that handles all email types:
* - Consumer emails (gmail.com, yahoo.com, etc.)
* - Business domains (mycompany.com using Google Workspace, etc.)
* - Unknown providers (graceful fallback)
*
* @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
*
* @example
* ```typescript
* // Consumer email
* const result = await getEmailProvider('local@domain.tld');
* console.log(result.provider?.companyProvider); // Provider name
* console.log(result.loginUrl); // Login URL
*
* // Business domain
* const business = await getEmailProvider('local@business.tld');
* console.log(business.provider?.companyProvider); // Detected provider
* console.log(business.detectionMethod); // Detection method
*
* // Error handling
* const invalid = await getEmailProvider('invalid-email');
* console.log(invalid.error?.type); // "INVALID_EMAIL"
* console.log(invalid.error?.message); // "Invalid email format"
* ```
*/
export declare function getEmailProvider(email: string, timeout?: number): Promise<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.
*
* @param email - The email address to analyze
* @returns EmailProviderResult with provider info (limited to known domains)
*
* @example
* ```typescript
* // Works for known domains
* const gmail = getEmailProviderSync('user@gmail.com');
* console.log(gmail.provider?.companyProvider); // "Gmail"
*
* // Unknown domains return null
* const unknown = getEmailProviderSync('user@mycompany.com');
* console.log(unknown.provider); // null
* console.log(unknown.error?.type); // "UNKNOWN_DOMAIN"
* ```
*/
export declare function getEmailProviderSync(email: string): EmailProviderResult;
/**
* 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'
* ```
*/
export declare function normalizeEmail(email: string): string;
/**
* 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
* ```
*/
export declare function emailsMatch(email1: string, email2: string): boolean;
/**
* Enhanced email provider detection with concurrent DNS for maximum performance.
* This function uses parallel MX/TXT lookups for 2x faster business domain detection.
*
* @param email - The email address to analyze
* @param options - Configuration options for DNS detection
* @returns Promise resolving to EmailProviderResult with enhanced performance data
*
* @example
* ```typescript
* // High-performance detection with concurrent DNS
* const result = await getEmailProviderFast('user@mycompany.com', {
* enableParallel: true,
* collectDebugInfo: true
* });
*
* console.log(result.provider?.companyProvider); // "Google Workspace"
* console.log(result.detectionMethod); // "mx_record"
* console.log(result.timing); // { mx: 120, txt: 95, total: 125 }
* ```
*/
export declare function getEmailProviderFast(email: string, options?: {
timeout?: number;
enableParallel?: boolean;
collectDebugInfo?: boolean;
}): Promise<EmailProviderResult & {
timing?: {
mx: number;
txt: number;
total: number;
};
confidence?: number;
debug?: any;
}>;
/**
* Configuration constants
*/
export declare const Config: {
readonly DEFAULT_DNS_TIMEOUT: 5000;
readonly MAX_DNS_REQUESTS_PER_MINUTE: 10;
readonly SUPPORTED_PROVIDERS_COUNT: 93;
readonly SUPPORTED_DOMAINS_COUNT: 180;
};
//# sourceMappingURL=api.d.ts.map