@mikkelscheike/email-provider-links 2.7.1 → 2.8.0

package/README.md

@@ -2,7 +2,11 @@
 
 🔒 **Modern email provider detection library with enhanced TypeScript support and enterprise security**
 
-A robust TypeScript library providing direct links to **93 email providers** (178 domains) with **concurrent DNS resolution**, **optimized performance**, **comprehensive email validation**, and advanced security features for login and password reset flows.
+A robust TypeScript library providing direct links to **93 email providers** (180 domains) with **concurrent DNS resolution**, **optimized performance**, **comprehensive email validation**, and advanced security features for login and password reset flows.
+
+## 🚀 Try it out
+
+**[Live Demo](https://demo.mikkelscheike.com)** - Test the library with any email address and see it in action!
 
 ## ✨ New in Version 2.7.0
 
@@ -13,12 +17,13 @@ A robust TypeScript library providing direct links to **93 email providers** (17
 - 🛡️ **Improved Security**: Enhanced cryptographic integrity verification
 - ⚡ **Better Performance**: Optimized concurrent DNS with smart caching
 - 🎯 **Developer Experience**: Enhanced error messages and debugging information
+- 📊 **Development Mode**: Memory usage tracking when NODE_ENV=development
 
 ## ✨ Core Features
 
-- 🚀 **Fast & Lightweight**: Zero dependencies, ultra-low memory (~0.39MB initial, ~0.02MB per 1000 ops)
+- 🚀 **Fast & Lightweight**: Zero dependencies, ultra-low memory (~0.08MB initial, ~0.03MB per 1000 ops)
 - 📧 **93 Email Providers**: Gmail, Outlook, Yahoo, ProtonMail, iCloud, and many more
-- 🌐 **178 Domains Supported**: Comprehensive international coverage
+- 🌐 **207 Domains Supported**: Comprehensive international coverage
 - 🌍 **Full IDN Support**: International domain names with RFC compliance and Punycode
 - ✅ **Advanced Email Validation**: International email validation with detailed error reporting
 - 🏢 **Business Domain Detection**: DNS-based detection for custom domains (Google Workspace, Microsoft 365, etc.)
@@ -31,7 +36,7 @@ A robust TypeScript library providing direct links to **93 email providers** (17
 - 🔄 **Email Alias Detection**: Normalize Gmail dots, plus addressing, and provider-specific aliases
 - 🛡️ **Fraud Prevention**: Detect duplicate accounts through email alias manipulation
 - 📦 **Batch Processing**: Efficiently process multiple emails with deduplication
-- 🧪 **Thoroughly Tested**: 396 tests with comprehensive code coverage
+- 🧪 **Thoroughly Tested**: 424 tests with 93.16% code coverage
 
 ## Installation
 
@@ -54,83 +59,9 @@ Fully compatible with the latest Node.js 24.x! The library is tested on:
 - Node.js 22.x (Current)
 - **Node.js 24.x (Latest)** - Full support with latest features
 
-## Quick Start
-
-**One function handles everything** - consumer emails, business domains, and unknown providers:
-
-```typescript
-import { getEmailProvider } from '@mikkelscheike/email-provider-links';
-
-// Works for ANY email address - the only function you need
-const result = await getEmailProvider('user@gmail.com');
-console.log(result.loginUrl);                    // "https://mail.google.com/mail/"
-console.log(result.provider?.companyProvider);   // "Gmail"
-
-// Automatically detects business domains too
-const business = await getEmailProvider('user@mycompany.com');
-console.log(business.provider?.companyProvider); // "Google Workspace" (if detected)
-
-// Gracefully handles unknown providers
-const unknown = await getEmailProvider('user@unknown.com');
-console.log(unknown.loginUrl);                   // null
-```
-
-## Enhanced Email Validation
-
-**New in 2.7.0**: Comprehensive email validation with international support:
-
-```typescript
-import { validateEmailAddress, validateInternationalEmail } from '@mikkelscheike/email-provider-links';
-
-// Enhanced validation with detailed error reporting
-const result = validateEmailAddress('user@example.com');
-if (result.isValid) {
-  console.log('Valid email:', result.normalizedEmail);
-} else {
-  console.log('Error:', result.error?.message);
-  console.log('Error code:', result.error?.code);
-}
-
-// International domain validation
-const intlResult = validateInternationalEmail('user@münchen.de');
-if (!intlResult) {
-  console.log('Valid international email');
-} else {
-  console.log('Validation error:', intlResult.message);
-}
-```
-
-## Batch Processing
-
-**New in 2.7.0**: Process multiple emails efficiently with deduplication:
-
-```typescript
-import { batchProcessEmails } from '@mikkelscheike/email-provider-links';
-
-const emails = [
-  'user@gmail.com',
-  'u.s.e.r+work@gmail.com',  // Alias of the first email
-  'test@yahoo.com',
-  'invalid-email'
-];
-
-const results = batchProcessEmails(emails, {
-  includeProviderInfo: true,
-  normalizeEmails: true,
-  deduplicateAliases: true
-});
-
-results.forEach(result => {
-  console.log(`${result.email}: ${result.isValid ? 'Valid' : 'Invalid'}`);
-  if (result.isDuplicate) {
-    console.log('  🔄 Duplicate detected');
-  }
-});
-```
-
 ## Supported Providers
 
-**📊 Current Coverage: 93 providers supporting 178 domains**
+**📊 Current Coverage: 93 providers supporting 207 domains**
 
 **Consumer Email Providers:**
 - **Gmail** (2 domains): gmail.com, googlemail.com
@@ -301,73 +232,36 @@ console.log(domain); // 'example.com'
 
 </details>
 
-## TypeScript Support
-
-Full TypeScript support with comprehensive interfaces:
-
-```typescript
-interface EmailProviderResult {
-  provider: EmailProvider | null;
-  email: string;
-  loginUrl: string | null;
-  detectionMethod?: 'domain_match' | 'mx_record' | 'txt_record' | 'both' | 'proxy_detected';
-  proxyService?: string;
-  error?: {
-    type: 'INVALID_EMAIL' | 'DNS_TIMEOUT' | 'RATE_LIMITED' | 'UNKNOWN_DOMAIN' | 
-          'NETWORK_ERROR' | 'IDN_VALIDATION_ERROR';
-    message: string;
-    retryAfter?: number;  // seconds until retry allowed (for rate limiting)
-    idnError?: string;    // specific IDN validation error message
-  };
-}
-
-interface ConfigConstants {
-  DEFAULT_DNS_TIMEOUT: number;          // 5000ms
-  MAX_DNS_REQUESTS_PER_MINUTE: number;  // 10 requests
-  SUPPORTED_PROVIDERS_COUNT: number;    // 93 providers
-  SUPPORTED_DOMAINS_COUNT: number;      // 178 domains
-}
-```
-
-## 🛡️ Security Features
+## Performance and Detection System
 
-This package implements **enterprise-grade security** to protect against malicious redirects and supply chain attacks:
+For detailed performance metrics and information about the detection system, refer to [Performance and Detection System](docs/PERFORMANCE.md).
 
-### ✅ Multi-Layer Protection
+### Development Mode Features
 
-- **HTTPS-Only Enforcement**: All provider URLs must use HTTPS protocol
-- **Domain Allowlisting**: Only pre-approved domains are allowed (93+ verified providers)
-- **Malicious Pattern Detection**: Blocks IP addresses, URL shorteners, suspicious TLDs
-- **Path Traversal Prevention**: Detects and blocks `../` and encoded variants
-- **JavaScript Injection Protection**: Prevents `javascript:`, `data:`, and script injections
-- **File Integrity Verification**: SHA-256 hash verification for provider database
+When `NODE_ENV` is set to 'development', the library provides additional insights:
 
-### 🔒 Attack Prevention
-
-Protects against common attack vectors:
-- ❌ **URL Injection**: Blocked by strict allowlisting
-- ❌ **Typosquatting**: Blocked by domain validation
-- ❌ **URL Shorteners**: Blocked by pattern detection
-- ❌ **Protocol Downgrade**: Blocked by HTTPS enforcement
-- ❌ **Path Traversal**: Blocked by path validation
-- ❌ **Script Injection**: Blocked by content validation
-- ❌ **Supply Chain Attacks**: Blocked by integrity verification
+```typescript
+// Memory usage is automatically logged:
+// 🚀 Current memory usage: 0.08 MB
+```
 
-### 🧪 Security Testing
+### Memory Management
 
-- **396 comprehensive tests** covering all functionality and edge cases
-- **92+ dedicated security tests** covering all attack vectors
-- **Automated security validation** in CI/CD pipeline
-- **Regular security audits** of provider database
+The library implements careful memory management:
+- Initial load: ~0.08MB heap usage
+- Batch operations: ~0.03MB per 1000 operations
+- Maximum load: < 25MB even under heavy concurrent operations
+- Automatic garbage collection hints
+- Memory usage logging in development mode
 
-## Performance Benchmarks
+### Performance Benchmarks
 
 This package is designed to be extremely memory efficient and fast:
 
-- **Provider loading**: ~0.39MB heap usage, <0.5ms
-- **Email lookups**: ~0.02MB heap usage per 100 operations
-- **Concurrent DNS**: ~0.03MB heap usage, ~110ms for 10 lookups
-- **Large scale (1000 ops)**: ~0.02MB heap usage, <3ms total
+- **Provider loading**: ~0.08MB heap usage, ~0.5ms
+- **Email lookups**: ~0.03MB heap usage per 100 operations
+- **Concurrent DNS**: ~0.03MB heap usage, ~27ms for 10 lookups
+- **Large scale (1000 ops)**: ~0.03MB heap usage, ~1.1ms total
 - **International validation**: <1ms for complex IDN domains
 
 To run benchmarks locally:
@@ -375,19 +269,11 @@ To run benchmarks locally:
 npm run benchmark
 ```
 
-## Examples
-
-Run the modern example to see all features in action:
-
-```bash
-npx tsx examples/modern-example.ts
-```
-
 ## Contributing
 
 We welcome contributions! See [CONTRIBUTING.md](docs/CONTRIBUTING.md) for guidelines on adding new email providers.
 
-**Quality Assurance**: This project maintains high standards with 396 comprehensive tests achieving excellent code coverage.
+**Quality Assurance**: This project maintains high standards with 424 comprehensive tests achieving 93.16% code coverage (96.46% function coverage).
 **Security Note**: All new providers undergo security validation and must pass our allowlist verification.
 
 ## Security
@@ -400,4 +286,4 @@ MIT License - see [LICENSE](LICENSE) file for details.
 
 ---
 
-**Zero dependencies • TypeScript-first • Production ready • International support**
+**Zero dependencies • TypeScript-first • Production ready • International support**

package/dist/api.d.ts

@@ -6,7 +6,7 @@
  */
 export interface EmailProvider {
     companyProvider: string;
-    loginUrl: string;
+    loginUrl: string | null;
     domains: string[];
     customDomainDetection?: {
         mxPatterns?: string[];

package/dist/api.js

@@ -215,9 +215,9 @@ function getEmailProviderSync(email) {
                 }
             };
         }
-        // Load providers and find matching domain
-        const { providers } = (0, loader_1.loadProviders)();
-        const provider = providers.find(p => p.domains?.some(d => d.toLowerCase() === domain));
+        // Use cached providers and domain map for efficient lookup
+        const { domainMap } = (0, loader_1.loadProviders)();
+        const provider = domainMap.get(domain);
         const result = {
             provider: provider || null,
             email,

package/dist/concurrent-dns.d.ts

@@ -4,7 +4,7 @@
  * Implements parallel MX/TXT record lookups for 2x faster business domain detection.
  * Uses Promise.allSettled for fault tolerance and intelligent result merging.
  */
-import { EmailProvider } from './index';
+import { EmailProvider } from './api';
 /**
  * Configuration for concurrent DNS detection
  */

package/dist/hash-verifier.js

@@ -27,9 +27,9 @@ const path_1 = require("path");
  */
 const KNOWN_GOOD_HASHES = {
     // SHA-256 hash of the legitimate emailproviders.json
-    'emailproviders.json': 'f77814bf0537019c6f38bf2744ae21640f04a2d39cb67c5116f6e03160c9486f',
+    'emailproviders.json': 'bdd4fe7d32a8760db2c2a2fcc9d2c07b32cc309f17eb6fd6c57753de0b5d623d',
     // You can add hashes for other critical files
-    'package.json': '67927e7e27636b55dc1fee5e34f16bbbf721a33103b0bc94c3c42923e2325cef'
+    'package.json': '86b76c6907a39775d96677b6d76719c8de6cadd256945134195513101beef489'
 };
 /**
  * Calculates SHA-256 hash of a file or string content

package/dist/loader.d.ts

@@ -3,7 +3,7 @@
  *
  * Handles loading email provider data with performance optimizations.
  */
-import { EmailProvider } from './index';
+import { EmailProvider } from './api';
 /**
  * Loading statistics for performance monitoring
  */

package/dist/loader.js

@@ -30,8 +30,8 @@ const DEFAULT_CONFIG = {
  */
 function convertProviderToEmailProvider(compressedProvider) {
     const provider = {
-        companyProvider: compressedProvider.name,
-        loginUrl: compressedProvider.url,
+        companyProvider: compressedProvider.companyProvider,
+        loginUrl: compressedProvider.loginUrl || null,
         domains: compressedProvider.domains || []
     };
     // Convert DNS detection patterns
@@ -92,6 +92,10 @@ function loadProvidersInternal(config = {}) {
             console.log(`⚡ Loading completed in ${loadTime}ms`);
             console.log(`📊 Stats: ${providers.length} providers, ${domainCount} domains`);
         }
+        if (process.env.NODE_ENV === 'development') {
+            const memoryUsageInMB = process.memoryUsage().heapUsed / 1024 / 1024;
+            console.log(`🚀 Current memory usage: ${memoryUsageInMB.toFixed(2)} MB`);
+        }
         return {
             providers,
             stats: loadingStats

package/dist/schema.d.ts

@@ -12,9 +12,9 @@ export interface Provider {
     /** Provider ID (short identifier) */
     id: string;
     /** Provider display name */
-    name: string;
-    /** Login/webmail URL */
-    url: string;
+    companyProvider: string;
+    /** Login/webmail URL (or null if not available) */
+    loginUrl: string | null;
     /** Email domains (omitted if empty) */
     domains?: string[];
     /** DNS detection patterns (flattened) */

package/dist/schema.js

@@ -51,14 +51,11 @@ function validateProvider(provider) {
     if (!provider.id || typeof provider.id !== 'string') {
         errors.push('Provider ID is required and must be a string');
     }
-    if (!provider.name || typeof provider.name !== 'string') {
-        errors.push('Provider name is required and must be a string');
+    if (!provider.companyProvider || typeof provider.companyProvider !== 'string') {
+        errors.push('Company provider is required and must be a string');
     }
-    if (!provider.url || typeof provider.url !== 'string') {
-        errors.push('Provider URL is required and must be a string');
-    }
-    else if (!provider.url.startsWith('https://')) {
-        errors.push('Provider URL must use HTTPS');
+    if (provider.loginUrl !== null && (typeof provider.loginUrl !== 'string' || !provider.loginUrl.startsWith('https://'))) {
+        errors.push('Login URL must be null or a string starting with HTTPS');
     }
     if (provider.domains && !Array.isArray(provider.domains)) {
         errors.push('Domains must be an array');

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@mikkelscheike/email-provider-links",
-  "version": "2.7.1",
-  "description": "TypeScript library for email provider detection with 93 providers (178 domains), concurrent DNS resolution, optimized performance, 91.75% test coverage, and enterprise security for login and password reset flows",
+  "version": "2.8.0",
+  "description": "TypeScript library for email provider detection with 93 providers (207 domains), concurrent DNS resolution, optimized performance, 91.75% test coverage, and enterprise security for login and password reset flows",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
   "files": [
@@ -62,17 +62,17 @@
     "access": "public"
   },
   "devDependencies": {
-    "@jest/globals": "^30.0.2",
+    "@jest/globals": "^30.0.3",
     "@semantic-release/commit-analyzer": "^13.0.1",
     "@semantic-release/exec": "^7.1.0",
     "@semantic-release/git": "^10.0.1",
     "@semantic-release/github": "^11.0.3",
-    "@semantic-release/npm": "^12.0.1",
+    "@semantic-release/npm": "^12.0.2",
     "@semantic-release/release-notes-generator": "^14.0.3",
     "@types/jest": "^30.0.0",
-    "@types/node": "^24.0.3",
+    "@types/node": "^24.0.4",
     "conventional-changelog-conventionalcommits": "^9.0.0",
-    "jest": "^30.0.2",
+    "jest": "^30.0.3",
     "semantic-release": "^24.2.5",
     "ts-jest": "^29.4.0",
     "tsx": "^4.20.3",