@mikkelscheike/email-provider-links
Version:
TypeScript library for email provider detection with 140 providers (259 domains), concurrent DNS resolution, alias normalization, and HTTPS login URL validation for login and password reset flows
174 lines • 6.18 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[];
};
}
/**
* 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 */
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;
};
}
/**
* 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.
*
* 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)
*
* 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 - Optional configuration: timeout for DNS queries (default: 5000ms) and extended response flag
* @returns Promise resolving to SimplifiedEmailProviderResult (default) or EmailProviderResult (if extended)
*/
export declare function getEmailProvider(email: string, options?: number | {
timeout?: number;
extended?: false;
}): Promise<SimplifiedEmailProviderResult>;
export declare function getEmailProvider(email: string, options: {
timeout?: number;
extended: true;
}): 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).
*
* Only checks predefined domains (no DNS). Use `extended: true` for full provider metadata.
*/
export declare function getEmailProviderSync(email: string, options?: {
extended?: false;
}): SimplifiedEmailProviderResult;
export declare function getEmailProviderSync(email: string, options: {
extended: true;
}): 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.
* Uses parallel MX/TXT lookups for faster business domain detection, and includes
* timing / confidence metadata for monitoring.
*
* Prefer `getEmailProvider()` unless you need timing or debug data.
*/
export declare function getEmailProviderFast(email: string, options?: {
timeout?: number;
enableParallel?: boolean;
collectDebugInfo?: boolean;
extended?: false;
}): Promise<SimplifiedEmailProviderResult & {
timing?: {
mx: number;
txt: number;
total: number;
};
confidence?: number;
debug?: unknown;
}>;
export declare function getEmailProviderFast(email: string, options: {
timeout?: number;
enableParallel?: boolean;
collectDebugInfo?: boolean;
extended: true;
}): Promise<EmailProviderResult & {
timing?: {
mx: number;
txt: number;
total: number;
};
confidence?: number;
debug?: unknown;
}>;
/**
* Configuration constants
*/
export declare const Config: {
readonly DEFAULT_DNS_TIMEOUT: 5000;
readonly MAX_DNS_REQUESTS_PER_MINUTE: 10;
readonly SUPPORTED_PROVIDERS_COUNT: 140;
readonly SUPPORTED_DOMAINS_COUNT: 259;
};
//# sourceMappingURL=api.d.ts.map