@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
114 lines • 3.71 kB
TypeScript
/**
* Email Alias Detection Module
*
* Clean, focused implementation with only essential functions.
* Detects and normalizes email aliases across different providers.
*
* Alias Configuration Behavior:
* ---------------------------
* The module handles email aliases based on provider-specific configurations.
* Each provider can specify how to handle three types of email variations:
*
* 1. Case sensitivity ("case")
* 2. Plus addressing ("plus")
* 3. Dots in username ("dots")
*
* Important: For each of these properties, modifications are only applied if
* explicitly configured in the provider's settings:
*
* - If a property is defined (e.g., "case": {"ignore": true, "strip": true}),
* the specified behavior is applied
*
* - If a property is missing from the provider's alias configuration,
* the original value is preserved without modification
*
* Example:
* ```json
* {
* "alias": {
* "dots": { "ignore": false, "strip": false },
* "plus": { "ignore": true, "strip": true }
* // case is not defined, so case will be preserved
* }
* }
* ```
*
* In this example:
* - Dots will be preserved (configured to not ignore/strip)
* - Plus addressing will be stripped (configured to ignore/strip)
* - Case will be preserved (not configured)
*
* Note: The domain part of email addresses is always converted to lowercase
* as per RFC 5321 standard, regardless of provider configuration.
*/
export interface AliasDetectionResult {
/** The normalized/canonical email address */
canonical: string;
/** The original email address */
original: string;
/** Whether an alias was detected */
isAlias: boolean;
/** Type of alias detected */
aliasType: 'plus' | 'dot' | 'none';
/** The alias part (if any) */
aliasPart?: string;
/** The provider that supports this alias type */
provider?: string;
}
/**
* Detects and analyzes email aliases
*
* This function processes email addresses according to provider-specific rules.
* Case is always lowercased in the canonical form for consistency and safety.
* It only applies additional modifications (plus, dots) that are explicitly
* defined in the provider's configuration.
*
* @param email - Email address to analyze
* @returns Detailed analysis of the email alias
*
* @example
* Provider with no case handling defined:
* ```typescript
* detectEmailAlias('User.Name@example.com')
* // Preserves case: User.Name@example.com
* ```
*
* Provider with case handling defined:
* ```typescript
* detectEmailAlias('User.Name@gmail.com')
* // Converts to lowercase: user.name@gmail.com
* ```
*/
export declare function detectEmailAlias(email: string): AliasDetectionResult;
/**
* Normalizes an email address to its canonical form.
*
* This is the primary function for preventing duplicate accounts.
*
* @param email - Email address to normalize
* @returns Canonical email address
*
* @example
* ```typescript
* const canonical = normalizeEmail('U.S.E.R+work@GMAIL.COM');
* console.log(canonical); // 'user@gmail.com'
* ```
*/
export declare function normalizeEmail(email: string): string;
/**
* Checks if two email addresses are the same when normalized.
*
* This is the primary function for matching aliases during login.
*
* @param email1 - First email address
* @param email2 - Second email address
* @returns true if the emails represent the same person
*
* @example
* ```typescript
* const match = emailsMatch('user@gmail.com', 'u.s.e.r+work@gmail.com');
* console.log(match); // true
* ```
*/
export declare function emailsMatch(email1: string, email2: string): boolean;
//# sourceMappingURL=alias-detection.d.ts.map