mailpop 1.0.0

package/dist/utils/normalize.js

@@ -0,0 +1,95 @@
+/**
+ * Normalizes an email address.
+ * - Trims whitespace
+ * - Converts to lowercase
+ * - Removes 'mailto:' prefix if present
+ * - Strips query parameters (e.g. ?subject=...)
+ * - Strips hash/fragment (e.g. #footer)
+ * - Removes any remaining URL encoded pieces or trailing dots
+ */
+export function normalizeEmail(email) {
+    let cleaned = email.trim().toLowerCase();
+    if (cleaned.startsWith('mailto:')) {
+        cleaned = cleaned.substring(7);
+    }
+    // Remove query parameters
+    const qMarkIndex = cleaned.indexOf('?');
+    if (qMarkIndex !== -1) {
+        cleaned = cleaned.substring(0, qMarkIndex);
+    }
+    // Remove hash/fragment
+    const hashIndex = cleaned.indexOf('#');
+    if (hashIndex !== -1) {
+        cleaned = cleaned.substring(0, hashIndex);
+    }
+    // URL decode if there are encoded characters
+    try {
+        cleaned = decodeURIComponent(cleaned);
+    }
+    catch (_e) {
+        // Keep as is if URL decoding fails
+    }
+    // Remove leading/trailing periods, quotes, or whitespace that might be captured in scraping
+    cleaned = cleaned.replace(/^['".\s]+|['".\s]+$/g, '');
+    return cleaned;
+}
+/**
+ * Normalizes a URL to ensure it has a valid protocol and is formatted consistently.
+ * @param url - The input URL string.
+ */
+export function normalizeUrl(url) {
+    let cleaned = url.trim();
+    if (!cleaned) {
+        return '';
+    }
+    if (!/^https?:\/\//i.test(cleaned)) {
+        cleaned = 'https://' + cleaned;
+    }
+    try {
+        const parsed = new URL(cleaned);
+        return parsed.href;
+    }
+    catch (_e) {
+        return cleaned;
+    }
+}
+/**
+ * Normalizes a domain name from a URL or raw string.
+ * @param domainOrUrl - Input string.
+ */
+export function normalizeDomain(domainOrUrl) {
+    let cleaned = domainOrUrl.trim().toLowerCase();
+    if (/^https?:\/\//i.test(cleaned)) {
+        try {
+            const parsed = new URL(cleaned);
+            cleaned = parsed.hostname;
+        }
+        catch (_e) {
+            // fallback regex
+            cleaned = cleaned.replace(/^https?:\/\/(www\.)?/, '');
+        }
+    }
+    cleaned = cleaned.replace(/^www\./i, '');
+    const slashIdx = cleaned.indexOf('/');
+    if (slashIdx !== -1) {
+        cleaned = cleaned.substring(0, slashIdx);
+    }
+    return cleaned;
+}
+/**
+ * Searches a raw CSV row record for columns representing the target website URL.
+ * Scans case-insensitively for fields like 'website', 'url', 'domain', 'site', 'web'.
+ */
+export function findWebsiteInRow(row) {
+    const candidateKeys = ['website', 'url', 'domain', 'site', 'web'];
+    for (const key of Object.keys(row)) {
+        const normalizedKey = key.toLowerCase().trim();
+        if (candidateKeys.some((candidate) => normalizedKey.includes(candidate))) {
+            const val = row[key];
+            if (val && val.trim()) {
+                return val.trim();
+            }
+        }
+    }
+    return null;
+}

package/dist/utils/retry.js

@@ -0,0 +1,29 @@
+import { delay } from './delay.js';
+/**
+ * Retries an asynchronous operation with exponential backoff.
+ * @param operation - The asynchronous function to execute.
+ * @param options - Configuration for retry count and delays.
+ */
+export async function retryWithBackoff(operation, options) {
+    let attempt = 0;
+    while (true) {
+        try {
+            return await operation();
+        }
+        catch (error) {
+            attempt++;
+            const err = error instanceof Error ? error : new Error(String(error));
+            if (attempt > options.maxRetries) {
+                throw err;
+            }
+            const backoffDelay = Math.min(options.initialDelayMs * Math.pow(2, attempt - 1), options.maxDelayMs);
+            // Add a small jitter (+/- 10%) to prevent thundering herd
+            const jitter = (Math.random() - 0.5) * 0.2 * backoffDelay;
+            const finalDelay = Math.max(0, backoffDelay + jitter);
+            if (options.onRetry) {
+                options.onRetry(err, attempt);
+            }
+            await delay(finalDelay);
+        }
+    }
+}

package/dist/utils/validators.js

@@ -0,0 +1,85 @@
+import { normalizeDomain } from './normalize.js';
+const EMAIL_REGEX = /^[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\.[a-zA-Z]{2,}$/;
+const REJECTED_PREFIXES = [
+    'noreply',
+    'no-reply',
+    'donotreply',
+    'do-not-reply',
+    'mailer-daemon',
+    'postmaster',
+    'abuse',
+    'security',
+    'spam',
+];
+const REJECTED_DOMAINS = [
+    'example.com',
+    'example.org',
+    'example.net',
+    'test.com',
+    'testing.com',
+    'domain.com',
+    'tempmail.com',
+    'yopmail.com',
+    'mailinator.com',
+    'sharklasers.com',
+    'guerrillamail.com',
+    'dispostable.com',
+    'getairmail.com',
+    '10minutemail.com',
+];
+/**
+ * Validates whether a string has a valid email format and is not in the blacklist.
+ * @param email - The email to check.
+ */
+export function isValidEmail(email) {
+    if (!EMAIL_REGEX.test(email)) {
+        return false;
+    }
+    const parts = email.split('@');
+    if (parts.length !== 2) {
+        return false;
+    }
+    const localPart = parts[0].toLowerCase().trim();
+    const domainPart = parts[1].toLowerCase().trim();
+    // Reject blacklisted prefixes
+    if (REJECTED_PREFIXES.includes(localPart)) {
+        return false;
+    }
+    // Reject blacklisted domains
+    if (REJECTED_DOMAINS.includes(domainPart)) {
+        return false;
+    }
+    // Simple heuristics for temporary or obviously fake emails
+    if (localPart.startsWith('noreply') ||
+        localPart.startsWith('no-reply') ||
+        localPart.startsWith('donotreply')) {
+        return false;
+    }
+    if (domainPart.includes('tempmail') ||
+        domainPart.includes('mailinator') ||
+        domainPart.includes('yopmail') ||
+        domainPart.startsWith('test.') ||
+        domainPart === 'test') {
+        return false;
+    }
+    // Exclude obviously invalid top level domains
+    const tld = domainPart.split('.').pop();
+    if (tld && (tld === 'local' || tld === 'temp' || tld === 'example')) {
+        return false;
+    }
+    return true;
+}
+/**
+ * Checks if the email domain matches the target company domain.
+ * @param email - The email to verify.
+ * @param targetDomainOrUrl - The target website/domain.
+ */
+export function isDomainMatch(email, targetDomainOrUrl) {
+    const parts = email.split('@');
+    if (parts.length !== 2) {
+        return false;
+    }
+    const emailDomain = normalizeDomain(parts[1]);
+    const targetDomain = normalizeDomain(targetDomainOrUrl);
+    return emailDomain === targetDomain || emailDomain.endsWith('.' + targetDomain);
+}

package/package.json

@@ -0,0 +1,46 @@
+{
+  "name": "mailpop",
+  "version": "1.0.0",
+  "description": "Production-ready public contact email discovery tool from company websites.",
+  "type": "module",
+  "main": "dist/index.js",
+  "bin": {
+    "mailpop": "dist/index.js"
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "dev": "tsx src/index.ts",
+    "build": "tsc",
+    "start": "node dist/index.js",
+    "lint": "eslint src",
+    "format": "prettier --write \"src/**/*.ts\"",
+    "typecheck": "tsc --noEmit"
+  },
+  "keywords": [
+    "email-hunter",
+    "lead-enrichment",
+    "playwright",
+    "cheerio",
+    "crawler",
+    "scraper"
+  ],
+  "author": "Antigravity",
+  "license": "MIT",
+  "dependencies": {
+    "cheerio": "^1.0.0-rc.12",
+    "dotenv": "^16.4.5",
+    "fast-csv": "^5.0.1",
+    "p-limit": "^6.1.0",
+    "playwright": "^1.49.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22.10.1",
+    "eslint": "^9.16.0",
+    "typescript-eslint": "^8.16.0",
+    "prettier": "^3.4.1",
+    "tsx": "^4.19.2",
+    "typescript": "^5.7.2"
+  }
+}