@mikkelscheike/email-provider-links 1.0.0

package/LICENSE

@@ -0,0 +1,22 @@
+MIT License
+
+Copyright (c) 2025 Email Provider Links
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+

package/README.md

@@ -0,0 +1,111 @@
+# Email Provider Links
+
+A TypeScript package that provides direct links to email providers based on email addresses to streamline login and password reset flows.
+
+## Features
+
+- 🚀 **Fast & Lightweight**: Zero dependencies, minimal footprint
+- 📧 **55+ Email Providers**: Gmail, Outlook, Yahoo, ProtonMail, and more
+- 🏢 **Business Domain Detection**: DNS-based detection for custom domains
+- 🔒 **Type Safe**: Full TypeScript support
+- ⚡ **Performance Optimized**: Smart DNS fallback with configurable timeouts
+
+## Installation
+
+```bash
+npm install @mikkelscheike/email-provider-links
+```
+
+## Quick Start
+
+```typescript
+import { getEmailProviderLinkWithDNS } from '@mikkelscheike/email-provider-links';
+
+// Works for any email address
+const result = await getEmailProviderLinkWithDNS('user@gmail.com');
+console.log(result.loginUrl); // "https://mail.google.com/mail/"
+
+// Business domains too
+const business = await getEmailProviderLinkWithDNS('user@mycompany.com');
+console.log(business.provider?.companyProvider); // "Google Workspace" (if detected)
+```
+
+## Supported Providers
+
+**Consumer Email:**
+Gmail, Outlook, Yahoo Mail, iCloud, ProtonMail, Zoho, AOL, GMX, Web.de, Mail.ru, QQ Mail, NetEase, Yandex, and more.
+
+**Business Email (via DNS detection):**
+Microsoft 365, Google Workspace, ProtonMail Business, FastMail, Tutanota, Zoho Workplace, and others.
+
+## API
+
+### `getEmailProviderLinkWithDNS(email, timeout?)`
+**Recommended** - Detects any email provider including business domains.
+
+```typescript
+const result = await getEmailProviderLinkWithDNS('user@gmail.com', 3000);
+// Returns: { provider, loginUrl, detectionMethod, email }
+```
+
+### `getEmailProviderLink(email)`
+**Synchronous** - Only checks predefined domains (no DNS lookup).
+
+```typescript
+const result = getEmailProviderLink('user@gmail.com');
+// Returns: { provider, loginUrl, email }
+```
+
+## Real-World Example
+
+```typescript
+async function handlePasswordReset(email: string) {
+  const result = await getEmailProviderLinkWithDNS(email);
+  
+  return {
+    providerUrl: result.loginUrl,
+    providerName: result.provider?.companyProvider || null,
+    isSupported: result.provider !== null
+  };
+}
+```
+
+## Configuration
+
+```typescript
+// Custom DNS timeout (default: 5000ms)
+const result = await getEmailProviderLinkWithDNS(email, 2000);
+
+// Check if provider is supported
+import { isEmailProviderSupported } from '@mikkelscheike/email-provider-links';
+const supported = isEmailProviderSupported('user@gmail.com');
+```
+
+## TypeScript Support
+
+```typescript
+interface EmailProviderResult {
+  provider: EmailProvider | null;
+  email: string;
+  loginUrl: string | null;
+  detectionMethod?: 'domain_match' | 'mx_record' | 'txt_record' | 'proxy_detected';
+  proxyService?: string;
+}
+```
+
+## Contributing
+
+We welcome contributions! See [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines on adding new email providers.
+
+## Security
+
+For security concerns, see our [Security Policy](SECURITY.md).
+
+## License
+
+MIT License - see [LICENSE](LICENSE) file for details.
+
+---
+
+**Zero dependencies • TypeScript-first • Production ready**
+

package/dist/index.d.ts

@@ -0,0 +1,317 @@
+/**
+ * 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
+ */
+/**
+ * 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"]
+ *   }
+ * }
+ * ```
+ */
+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[];
+    };
+}
+/**
+ * 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.
+ */
+export declare function isValidEmail(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.
+ */
+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.
+ */
+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. Performs MX record lookup for the domain
+ * 2. Checks if MX records match known proxy services (Cloudflare, etc.)
+ * 3. If proxy detected, returns null provider with proxy info
+ * 4. Otherwise, matches MX records against business email provider patterns
+ * 5. If no MX match, falls back to TXT record analysis (SPF records, etc.)
+ * 6. Returns the first matching provider or null if none found
+ *
+ * **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>;
+/**
+ * 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
+ */
+export declare function getEmailProviderLinkWithDNS(email: string, timeoutMs?: number): Promise<EmailProviderResult>;
+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;
+};
+export default _default;
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAyCH;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,WAAW,aAAa;IAC5B,wDAAwD;IACxD,eAAe,EAAE,MAAM,CAAC;IACxB,sDAAsD;IACtD,QAAQ,EAAE,MAAM,CAAC;IACjB,2FAA2F;IAC3F,OAAO,EAAE,MAAM,EAAE,CAAC;IAClB,wEAAwE;IACxE,qBAAqB,CAAC,EAAE;QACtB,yEAAyE;QACzE,UAAU,CAAC,EAAE,MAAM,EAAE,CAAC;QACtB,sFAAsF;QACtF,WAAW,CAAC,EAAE,MAAM,EAAE,CAAC;KACxB,CAAC;CACH;AAED;;;;;;;;;;;;;GAaG;AACH,MAAM,WAAW,mBAAmB;IAClC,qEAAqE;IACrE,QAAQ,EAAE,aAAa,GAAG,IAAI,CAAC;IAC/B,mDAAmD;IACnD,KAAK,EAAE,MAAM,CAAC;IACd,wEAAwE;IACxE,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;IACxB,yCAAyC;IACzC,eAAe,CAAC,EAAE,cAAc,GAAG,WAAW,GAAG,YAAY,GAAG,gBAAgB,CAAC;IACjF,0EAA0E;IAC1E,YAAY,CAAC,EAAE,MAAM,CAAC;CACvB;AAED;;;;;;;;;;;;GAYG;AACH,MAAM,WAAW,kBAAkB;IACjC,qEAAqE;IACrE,QAAQ,EAAE,aAAa,GAAG,IAAI,CAAC;IAC/B,0CAA0C;IAC1C,eAAe,EAAE,WAAW,GAAG,YAAY,GAAG,gBAAgB,GAAG,IAAI,CAAC;IACtE,0EAA0E;IAC1E,YAAY,CAAC,EAAE,MAAM,CAAC;CACvB;AAuDD;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,YAAY,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAGnD;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,aAAa,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAO1D;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,MAAM,GAAG,aAAa,GAAG,IAAI,CAGtE;AAED;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,wBAAgB,oBAAoB,CAAC,KAAK,EAAE,MAAM,GAAG,mBAAmB,CAkBvE;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,qBAAqB,IAAI,aAAa,EAAE,CAEvD;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,wBAAwB,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAG/D;AAsDD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmCG;AACH,wBAAsB,mBAAmB,CAAC,MAAM,EAAE,MAAM,EAAE,SAAS,GAAE,MAA4B,GAAG,OAAO,CAAC,kBAAkB,CAAC,CAwE9H;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAwDG;AACH,wBAAsB,2BAA2B,CAAC,KAAK,EAAE,MAAM,EAAE,SAAS,GAAE,MAA4B,GAAG,OAAO,CAAC,mBAAmB,CAAC,CAmDtI;;;;;;;;;;;AAGD,wBASE"}