linkedin-secret-sauce 0.11.0 → 0.11.1

package/dist/enrichment/verification/mx.js

@@ -3,12 +3,52 @@
  * MX Record Resolution and Email Verification
  *
  * Provides MX record resolution with timeout support and confidence scoring.
+ * Includes SMTP-based catch-all detection using RCPT TO verification.
  */
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.verifyEmailsExist = verifyEmailsExist;
+exports.checkDomainCatchAll = checkDomainCatchAll;
 exports.verifyEmailMx = verifyEmailMx;
 const promises_1 = require("node:dns/promises");
+const net = __importStar(require("node:net"));
 const disposable_domains_1 = require("../utils/disposable-domains");
 const validation_1 = require("../utils/validation");
+// Cache for catch-all results (domain -> isCatchAll)
+const catchAllCache = new Map();
+const CACHE_TTL_MS = 24 * 60 * 60 * 1000; // 24 hours
 /**
  * Resolve MX records with timeout
  *
@@ -30,6 +70,273 @@ async function resolveMxWithTimeout(domain, timeoutMs) {
         clearTimeout(timeoutId);
     }
 }
+/**
+ * Generate a random string for catch-all testing
+ */
+function generateRandomLocalPart() {
+    const chars = 'abcdefghijklmnopqrstuvwxyz0123456789';
+    let result = 'catchalltest_';
+    for (let i = 0; i < 16; i++) {
+        result += chars.charAt(Math.floor(Math.random() * chars.length));
+    }
+    return result;
+}
+/**
+ * Detect if a domain is a catch-all by testing with a random email address
+ * Uses SMTP RCPT TO verification
+ *
+ * @param domain - Domain to test
+ * @param mxHost - MX server hostname
+ * @param timeoutMs - Timeout in milliseconds
+ * @returns true if catch-all, false if not, null if unable to determine
+ */
+async function detectCatchAll(domain, mxHost, timeoutMs = 10000) {
+    // Check cache first
+    const cached = catchAllCache.get(domain);
+    if (cached && Date.now() - cached.timestamp < CACHE_TTL_MS) {
+        return cached.isCatchAll;
+    }
+    return new Promise((resolve) => {
+        const randomEmail = `${generateRandomLocalPart()}@${domain}`;
+        const socket = new net.Socket();
+        let step = 0;
+        let responseBuffer = '';
+        const cleanup = () => {
+            socket.removeAllListeners();
+            socket.destroy();
+        };
+        const timeout = setTimeout(() => {
+            cleanup();
+            resolve(null); // Unable to determine
+        }, timeoutMs);
+        socket.on('error', () => {
+            clearTimeout(timeout);
+            cleanup();
+            resolve(null); // Unable to determine
+        });
+        socket.on('close', () => {
+            clearTimeout(timeout);
+            cleanup();
+        });
+        socket.on('data', (data) => {
+            responseBuffer += data.toString();
+            // Process complete lines
+            const lines = responseBuffer.split('\r\n');
+            responseBuffer = lines.pop() || ''; // Keep incomplete line in buffer
+            for (const line of lines) {
+                if (!line)
+                    continue;
+                const code = parseInt(line.substring(0, 3), 10);
+                switch (step) {
+                    case 0: // Waiting for greeting
+                        if (code === 220) {
+                            step = 1;
+                            socket.write(`HELO verify.local\r\n`);
+                        }
+                        else {
+                            cleanup();
+                            resolve(null);
+                        }
+                        break;
+                    case 1: // Waiting for HELO response
+                        if (code === 250) {
+                            step = 2;
+                            socket.write(`MAIL FROM:<test@verify.local>\r\n`);
+                        }
+                        else {
+                            cleanup();
+                            resolve(null);
+                        }
+                        break;
+                    case 2: // Waiting for MAIL FROM response
+                        if (code === 250) {
+                            step = 3;
+                            socket.write(`RCPT TO:<${randomEmail}>\r\n`);
+                        }
+                        else {
+                            cleanup();
+                            resolve(null);
+                        }
+                        break;
+                    case 3: // Waiting for RCPT TO response - this is the key!
+                        clearTimeout(timeout);
+                        socket.write('QUIT\r\n');
+                        // 250 = accepted (catch-all)
+                        // 550, 551, 552, 553 = rejected (not catch-all)
+                        // Other codes = unable to determine
+                        const isCatchAll = code === 250;
+                        const isRejected = code >= 550 && code <= 559;
+                        if (isCatchAll || isRejected) {
+                            // Cache the result
+                            catchAllCache.set(domain, {
+                                isCatchAll,
+                                timestamp: Date.now(),
+                            });
+                            cleanup();
+                            resolve(isCatchAll);
+                        }
+                        else {
+                            cleanup();
+                            resolve(null);
+                        }
+                        break;
+                }
+            }
+        });
+        // Connect to MX server on port 25
+        socket.connect(25, mxHost);
+    });
+}
+/**
+ * Verify if a specific email address exists via SMTP RCPT TO
+ *
+ * @param email - Email address to verify
+ * @param mxHost - MX server hostname
+ * @param timeoutMs - Timeout in milliseconds
+ * @returns true if exists, false if not, null if unable to determine
+ */
+async function verifyEmailExists(email, mxHost, timeoutMs = 10000) {
+    return new Promise((resolve) => {
+        const socket = new net.Socket();
+        let step = 0;
+        let responseBuffer = '';
+        const cleanup = () => {
+            socket.removeAllListeners();
+            socket.destroy();
+        };
+        const timeout = setTimeout(() => {
+            cleanup();
+            resolve(null);
+        }, timeoutMs);
+        socket.on('error', () => {
+            clearTimeout(timeout);
+            cleanup();
+            resolve(null);
+        });
+        socket.on('close', () => {
+            clearTimeout(timeout);
+            cleanup();
+        });
+        socket.on('data', (data) => {
+            responseBuffer += data.toString();
+            const lines = responseBuffer.split('\r\n');
+            responseBuffer = lines.pop() || '';
+            for (const line of lines) {
+                if (!line)
+                    continue;
+                const code = parseInt(line.substring(0, 3), 10);
+                switch (step) {
+                    case 0: // Waiting for greeting
+                        if (code === 220) {
+                            step = 1;
+                            socket.write(`HELO verify.local\r\n`);
+                        }
+                        else {
+                            cleanup();
+                            resolve(null);
+                        }
+                        break;
+                    case 1: // Waiting for HELO response
+                        if (code === 250) {
+                            step = 2;
+                            socket.write(`MAIL FROM:<test@verify.local>\r\n`);
+                        }
+                        else {
+                            cleanup();
+                            resolve(null);
+                        }
+                        break;
+                    case 2: // Waiting for MAIL FROM response
+                        if (code === 250) {
+                            step = 3;
+                            socket.write(`RCPT TO:<${email}>\r\n`);
+                        }
+                        else {
+                            cleanup();
+                            resolve(null);
+                        }
+                        break;
+                    case 3: // Waiting for RCPT TO response
+                        clearTimeout(timeout);
+                        socket.write('QUIT\r\n');
+                        // 250 = accepted (email exists or catch-all)
+                        // 550, 551, 552, 553 = rejected (email doesn't exist)
+                        const exists = code === 250;
+                        const rejected = code >= 550 && code <= 559;
+                        if (exists || rejected) {
+                            cleanup();
+                            resolve(exists);
+                        }
+                        else {
+                            cleanup();
+                            resolve(null);
+                        }
+                        break;
+                }
+            }
+        });
+        socket.connect(25, mxHost);
+    });
+}
+/**
+ * Verify multiple email addresses with rate limiting
+ *
+ * @param emails - Array of email addresses to verify
+ * @param options - Options including delay between checks
+ * @returns Array of verification results
+ */
+async function verifyEmailsExist(emails, options) {
+    const delayMs = options?.delayMs ?? 3000; // 3 second delay between checks
+    const timeoutMs = options?.timeoutMs ?? 10000;
+    const results = [];
+    // Group emails by domain to reuse MX lookups
+    const emailsByDomain = new Map();
+    for (const email of emails) {
+        const domain = email.split('@')[1]?.toLowerCase();
+        if (domain) {
+            const existing = emailsByDomain.get(domain) || [];
+            existing.push(email);
+            emailsByDomain.set(domain, existing);
+        }
+        else {
+            results.push({ email, exists: null, mxHost: null, error: 'Invalid email format' });
+        }
+    }
+    // Process each domain
+    for (const [domain, domainEmails] of emailsByDomain) {
+        // Get MX records for domain
+        const mx = await resolveMxWithTimeout(domain, 5000);
+        if (!mx || mx.length === 0) {
+            for (const email of domainEmails) {
+                results.push({ email, exists: null, mxHost: null, error: 'No MX records found' });
+            }
+            continue;
+        }
+        const sortedMx = mx.sort((a, b) => a.priority - b.priority);
+        const mxHost = sortedMx[0].exchange;
+        // Verify each email with delay
+        for (let i = 0; i < domainEmails.length; i++) {
+            const email = domainEmails[i];
+            // Add delay between checks (except for first one)
+            if (i > 0) {
+                await new Promise((resolve) => setTimeout(resolve, delayMs));
+            }
+            try {
+                const exists = await verifyEmailExists(email, mxHost, timeoutMs);
+                results.push({ email, exists, mxHost });
+            }
+            catch (err) {
+                results.push({
+                    email,
+                    exists: null,
+                    mxHost,
+                    error: err instanceof Error ? err.message : 'Verification failed',
+                });
+            }
+        }
+    }
+    return results;
+}
 /**
  * Calculate confidence score based on verification factors
  */
@@ -43,9 +350,14 @@ function calculateConfidence(params) {
         score += 20;
     else if (mxCount === 1)
         score += 10;
-    // Non-catch-all bonus (we assume catch-all if MX exists but can't verify)
-    if (!isCatchAll)
+    // Catch-all scoring:
+    // - Not catch-all (false): +30 bonus
+    // - Is catch-all (true): no bonus
+    // - Unknown (null): +15 (partial bonus)
+    if (isCatchAll === false)
         score += 30;
+    else if (isCatchAll === null)
+        score += 15;
     // Non-role account bonus
     if (!isRoleAccount)
         score += 20;
@@ -61,8 +373,50 @@ function calculateConfidence(params) {
  * @param options - Verification options
  * @returns Verification result with confidence score
  */
+/**
+ * Check if a domain is a catch-all (accepts all email addresses)
+ *
+ * @param domain - Domain to check
+ * @param options - Options including timeout
+ * @returns Object with isCatchAll status and MX records
+ */
+async function checkDomainCatchAll(domain, options) {
+    const timeoutMs = options?.timeoutMs ?? 10000;
+    try {
+        // Get MX records
+        const mx = await resolveMxWithTimeout(domain, 5000);
+        if (!mx || mx.length === 0) {
+            return {
+                isCatchAll: null,
+                mxRecords: [],
+                mxHost: null,
+                error: 'No MX records found',
+            };
+        }
+        // Sort by priority and get primary
+        const sortedMx = mx.sort((a, b) => a.priority - b.priority);
+        const primaryMxHost = sortedMx[0].exchange;
+        const mxRecords = sortedMx.map((m) => m.exchange);
+        // Detect catch-all
+        const isCatchAll = await detectCatchAll(domain, primaryMxHost, timeoutMs);
+        return {
+            isCatchAll,
+            mxRecords,
+            mxHost: primaryMxHost,
+        };
+    }
+    catch (err) {
+        return {
+            isCatchAll: null,
+            mxRecords: [],
+            mxHost: null,
+            error: err instanceof Error ? err.message : 'Unknown error',
+        };
+    }
+}
 async function verifyEmailMx(email, options) {
     const timeoutMs = options?.timeoutMs ?? 5000;
+    const checkCatchAll = options?.checkCatchAll ?? false;
     // Step 1: Syntax validation
     if (!(0, validation_1.isValidEmailSyntax)(email)) {
         return {
@@ -113,8 +467,14 @@ async function verifyEmailMx(email, options) {
                 mxRecords: [],
             };
         }
-        // Conservative: assume catch-all if MX exists (full detection requires SMTP handshake)
-        const catchAll = true;
+        // Sort MX records by priority (lowest first)
+        const sortedMx = mx.sort((a, b) => a.priority - b.priority);
+        const primaryMxHost = sortedMx[0].exchange;
+        // Detect catch-all if requested (uses SMTP RCPT TO verification)
+        let catchAll = null;
+        if (checkCatchAll) {
+            catchAll = await detectCatchAll(domain, primaryMxHost, timeoutMs);
+        }
         // Calculate confidence
         const confidence = calculateConfidence({
             mxValid: true,
@@ -127,17 +487,17 @@ async function verifyEmailMx(email, options) {
         // Determine reason
         let reason = 'valid';
         if (!valid) {
-            if (catchAll)
+            if (catchAll === true)
                 reason = 'catch_all';
             else if (roleAccount)
                 reason = 'role_account';
         }
-        const mxRecords = mx.map((m) => m.exchange);
+        const mxRecords = sortedMx.map((m) => m.exchange);
         return {
             valid,
             confidence,
             reason,
-            isCatchAll: catchAll,
+            isCatchAll: catchAll ?? false, // Default to false if unknown
             isRoleAccount: roleAccount,
             isDisposable: false,
             mxRecords,

package/dist/index.d.ts

@@ -1,18 +1,208 @@
+/**
+ * LinkedIn Secret Sauce
+ *
+ * A complete LinkedIn Sales Navigator client + Email Enrichment library.
+ *
+ * ## Two Main Modules
+ *
+ * ### 1. LinkedIn API
+ * Server-side LinkedIn Sales Navigator client with automatic cookie management,
+ * retries, caching, and parsing.
+ *
+ * ```typescript
+ * import { initializeLinkedInClient, searchSalesLeads, getProfileByVanity } from 'linkedin-secret-sauce';
+ *
+ * initializeLinkedInClient({
+ *   cosiallApiUrl: process.env.COSIALL_API_URL,
+ *   cosiallApiKey: process.env.COSIALL_API_KEY,
+ * });
+ *
+ * const profile = await getProfileByVanity('john-doe');
+ * const leads = await searchSalesLeads('cto fintech', { count: 25 });
+ * ```
+ *
+ * ### 2. Email Enrichment
+ * Find business emails using multiple providers with waterfall/parallel strategies.
+ *
+ * ```typescript
+ * import { createEnrichmentClient } from 'linkedin-secret-sauce';
+ *
+ * const enrichment = createEnrichmentClient({
+ *   providers: {
+ *     hunter: { apiKey: process.env.HUNTER_API_KEY },
+ *     bouncer: { apiKey: process.env.BOUNCER_API_KEY },
+ *   },
+ * });
+ *
+ * const result = await enrichment.enrich({
+ *   firstName: 'John',
+ *   lastName: 'Doe',
+ *   domain: 'acme.com',
+ * });
+ * console.log(result.business_email); // john.doe@acme.com
+ * ```
+ *
+ * @packageDocumentation
+ */
 export { initializeLinkedInClient, getConfig } from "./config";
 export type { LinkedInClientConfig } from "./config";
+export * from "./linkedin-api";
+export * from "./types";
+export type { LinkedInTenure, LinkedInPosition, LinkedInSpotlightBadge, SalesLeadSearchResult, } from "./types";
 export { LinkedInClientError } from "./utils/errors";
 export * from "./cosiall-client";
 export * from "./cookie-pool";
 export { parseFullProfile } from "./parsers/profile-parser";
 export { parseSalesSearchResults } from "./parsers/search-parser";
-export * from "./linkedin-api";
-export * from "./types";
-export type { LinkedInTenure, LinkedInPosition, LinkedInSpotlightBadge, SalesLeadSearchResult, } from "./types";
 export * from "./utils/metrics";
 export { getRequestHistory, clearRequestHistory, } from "./utils/request-history";
 export type { RequestHistoryEntry } from "./utils/request-history";
 export * from "./constants";
+/**
+ * Create an enrichment client for finding business emails
+ *
+ * @example
+ * ```typescript
+ * const enrichment = createEnrichmentClient({
+ *   providers: {
+ *     construct: {},  // FREE pattern matching
+ *     hunter: { apiKey: 'xxx' },
+ *     bouncer: { apiKey: 'xxx' },
+ *   },
+ *   onCost: (provider, cost) => console.log(`${provider}: $${cost}`),
+ * });
+ *
+ * const result = await enrichment.enrich({
+ *   firstName: 'John',
+ *   lastName: 'Doe',
+ *   domain: 'acme.com',
+ * });
+ * ```
+ */
 export { createEnrichmentClient } from "./enrichment";
-export type { CanonicalEmail, EnrichmentCandidate, ProviderResult, ProviderFunc, ProviderName, EnrichmentClientConfig, EnrichmentClient, ProvidersConfig, EnrichmentOptions, BatchEnrichmentOptions, HunterConfig, ApolloConfig, SmartProspectConfig, LddConfig, DropcontactConfig, ConstructConfig, CacheAdapter, CostCallback, EnrichmentLogger, VerificationResult, SmartProspectContact, SmartProspectSearchFilters, LddProfileData, LddApiResponse, } from "./enrichment";
-export { isPersonalEmail, isBusinessEmail, isPersonalDomain, isDisposableEmail, isDisposableDomain, isValidEmailSyntax, isRoleAccount, verifyEmailMx, PERSONAL_DOMAINS, DISPOSABLE_DOMAINS, DEFAULT_PROVIDER_ORDER, PROVIDER_COSTS, getSmartLeadToken, getSmartLeadUser, clearSmartLeadToken, clearAllSmartLeadTokens, getSmartLeadTokenCacheStats, } from "./enrichment";
-export type { SmartLeadCredentials, SmartLeadAuthConfig, SmartLeadUser, SmartLeadLoginResponse, } from "./enrichment";
+export type { 
+/** Result returned by enrichment operations */
+CanonicalEmail, 
+/** Input candidate for email lookup */
+EnrichmentCandidate, 
+/** Raw provider result */
+ProviderResult, 
+/** Provider function signature */
+ProviderFunc, 
+/** Supported provider names */
+ProviderName, 
+/** Full client configuration */
+EnrichmentClientConfig, 
+/** Enrichment client interface */
+EnrichmentClient, 
+/** Provider configuration map */
+ProvidersConfig, 
+/** Enrichment options */
+EnrichmentOptions, 
+/** Batch processing options */
+BatchEnrichmentOptions, 
+/** Hunter.io configuration */
+HunterConfig, 
+/** SmartProspect/SmartLead configuration */
+SmartProspectConfig, 
+/** LinkedIn Data Dump configuration */
+LddConfig, 
+/** Dropcontact configuration */
+DropcontactConfig, 
+/** Construct provider configuration */
+ConstructConfig, 
+/** Cache adapter interface */
+CacheAdapter, 
+/** Cost tracking callback */
+CostCallback, 
+/** Logger interface */
+EnrichmentLogger, 
+/** Email verification result */
+VerificationResult, 
+/** SmartProspect contact */
+SmartProspectContact, 
+/** SmartProspect search filters */
+SmartProspectSearchFilters, 
+/** LDD profile data */
+LddProfileData, 
+/** LDD API response */
+LddApiResponse, } from "./enrichment";
+export { 
+/**
+ * Check if email is from a personal domain (Gmail, Yahoo, etc.)
+ * @example isPersonalEmail('john@gmail.com') // true
+ */
+isPersonalEmail, 
+/**
+ * Check if email is from a business domain
+ * @example isBusinessEmail('john@acme.com') // true
+ */
+isBusinessEmail, 
+/**
+ * Check if domain is a personal email provider
+ * @example isPersonalDomain('gmail.com') // true
+ */
+isPersonalDomain, 
+/**
+ * Check if email is from a disposable/temporary email service
+ * @example isDisposableEmail('test@mailinator.com') // true
+ */
+isDisposableEmail, 
+/**
+ * Check if domain is a disposable email provider
+ * @example isDisposableDomain('guerrillamail.com') // true
+ */
+isDisposableDomain, 
+/**
+ * Validate email syntax
+ * @example isValidEmailSyntax('john@example.com') // true
+ */
+isValidEmailSyntax, 
+/**
+ * Check if email is a role account (info@, support@, etc.)
+ * @example isRoleAccount('info@company.com') // true
+ */
+isRoleAccount, 
+/**
+ * Verify email via MX record lookup
+ */
+verifyEmailMx, 
+/** Set of known personal email domains */
+PERSONAL_DOMAINS, 
+/** Set of known disposable email domains */
+DISPOSABLE_DOMAINS, 
+/** Default provider execution order */
+DEFAULT_PROVIDER_ORDER, 
+/** Cost per lookup by provider (USD) */
+PROVIDER_COSTS, } from "./enrichment";
+export { 
+/**
+ * Get JWT token for SmartLead API (cached, auto-refreshes)
+ * @example const token = await getSmartLeadToken({ credentials: { email, password } });
+ */
+getSmartLeadToken, 
+/**
+ * Get SmartLead user info from cached login
+ */
+getSmartLeadUser, 
+/**
+ * Clear cached token for an email (e.g., on 401 error)
+ */
+clearSmartLeadToken, 
+/**
+ * Clear all cached SmartLead tokens
+ */
+clearAllSmartLeadTokens, 
+/**
+ * Get token cache statistics for debugging
+ */
+getSmartLeadTokenCacheStats, } from "./enrichment";
+export type { 
+/** SmartLead login credentials */
+SmartLeadCredentials, 
+/** SmartLead authentication configuration */
+SmartLeadAuthConfig, 
+/** SmartLead user info */
+SmartLeadUser, 
+/** SmartLead login response */
+SmartLeadLoginResponse, } from "./enrichment";