linkedin-secret-sauce 0.5.1 → 0.7.1

package/dist/enrichment/orchestrator.js

@@ -8,12 +8,15 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.enrichBusinessEmail = enrichBusinessEmail;
 exports.enrichBatch = enrichBatch;
+exports.enrichAllEmails = enrichAllEmails;
+exports.enrichAllBatch = enrichAllBatch;
 const personal_domains_1 = require("./utils/personal-domains");
 const disposable_domains_1 = require("./utils/disposable-domains");
+const validation_1 = require("./utils/validation");
 /**
  * Default provider costs in USD per lookup
  */
-const DEFAULT_PROVIDER_COSTS = {
+const _PROVIDER_COSTS = {
     construct: 0,
     ldd: 0,
     smartprospect: 0.01,
@@ -60,7 +63,13 @@ function getProviderName(provider, index) {
  * Get provider cost
  */
 function getProviderCost(providerName) {
-    return DEFAULT_PROVIDER_COSTS[providerName] ?? 0;
+    return _PROVIDER_COSTS[providerName] ?? 0;
+}
+/**
+ * Check if a provider result is a multi-result (returns multiple emails)
+ */
+function isMultiResult(result) {
+    return result !== null && 'emails' in result && Array.isArray(result.emails);
 }
 /**
  * Enrich a single candidate with business email
@@ -93,7 +102,7 @@ async function enrichBusinessEmail(candidate, options) {
             raw = await provider(candidate);
             logger?.debug?.('enrichment.provider.done', {
                 provider: providerName,
-                hasResult: !!raw?.email,
+                hasResult: !!(raw && (isMultiResult(raw) ? raw.emails.length > 0 : raw.email)),
             });
         }
         catch (error) {
@@ -108,7 +117,7 @@ async function enrichBusinessEmail(candidate, options) {
                     raw = await provider(candidate);
                     logger?.debug?.('enrichment.provider.retry.done', {
                         provider: providerName,
-                        hasResult: !!raw?.email,
+                        hasResult: !!(raw && (isMultiResult(raw) ? raw.emails.length > 0 : raw.email)),
                     });
                 }
                 catch {
@@ -116,6 +125,20 @@ async function enrichBusinessEmail(candidate, options) {
                 }
             }
         }
+        // Convert multi-result to single result (take best match for backwards compatibility)
+        let singleResult = null;
+        if (isMultiResult(raw) && raw.emails.length > 0) {
+            // Take the first (highest confidence) email
+            const best = raw.emails[0];
+            singleResult = {
+                email: best.email,
+                verified: best.verified,
+                confidence: best.confidence,
+            };
+        }
+        else if (raw && !isMultiResult(raw)) {
+            singleResult = raw;
+        }
         // Deduct cost (even on failure - API was called)
         if (stepCost > 0) {
             remaining = Math.max(0, remaining - stepCost);
@@ -134,7 +157,7 @@ async function enrichBusinessEmail(candidate, options) {
             });
         }
         // Normalize result
-        const normalized = normalizeProviderResult(providerName, raw);
+        const normalized = normalizeProviderResult(providerName, singleResult);
         // Skip if no email found
         if (!normalized.business_email) {
             continue;
@@ -216,3 +239,197 @@ async function enrichBatch(candidates, options) {
     }
     return results;
 }
+// =============================================================================
+// Multi-Email Enrichment (Collect All)
+// =============================================================================
+/**
+ * Classify an email's type based on domain characteristics
+ */
+function classifyEmailType(email) {
+    if ((0, disposable_domains_1.isDisposableEmail)(email)) {
+        return 'disposable';
+    }
+    if ((0, personal_domains_1.isPersonalEmail)(email)) {
+        return 'personal';
+    }
+    if ((0, validation_1.isRoleAccount)(email)) {
+        return 'role';
+    }
+    // If it's not personal, disposable, or role, it's likely business
+    return 'business';
+}
+/**
+ * Enrich a candidate and collect ALL emails from ALL providers
+ *
+ * Unlike enrichBusinessEmail which stops at the first valid match,
+ * this function queries all providers (respecting budget) and returns
+ * all found emails with their scores and classifications.
+ */
+async function enrichAllEmails(candidate, options) {
+    const { providers, maxCostPerEmail = Infinity, retryMs = 200, onCost, logger, } = options;
+    // Track results
+    const allEmails = [];
+    const providersQueried = [];
+    let totalCost = 0;
+    // Track remaining budget
+    let remaining = Number.isFinite(maxCostPerEmail) && maxCostPerEmail >= 0 ? maxCostPerEmail : Infinity;
+    // Track seen emails to avoid duplicates
+    const seenEmails = new Set();
+    logger?.debug?.('enrichment.all.start', {
+        providers: providers.length,
+        maxCostPerEmail,
+    });
+    for (let i = 0; i < providers.length; i++) {
+        const provider = providers[i];
+        const providerName = getProviderName(provider, i);
+        const stepCost = getProviderCost(providerName);
+        // Skip if cost exceeds remaining budget
+        if (stepCost > 0 && remaining < stepCost) {
+            logger?.debug?.('enrichment.all.skip_budget', {
+                provider: providerName,
+                cost: stepCost,
+                remaining,
+            });
+            continue;
+        }
+        providersQueried.push(providerName);
+        let raw = null;
+        try {
+            logger?.debug?.('enrichment.all.provider.start', { provider: providerName });
+            raw = await provider(candidate);
+            logger?.debug?.('enrichment.all.provider.done', {
+                provider: providerName,
+                hasResult: !!raw,
+                isMulti: isMultiResult(raw),
+            });
+        }
+        catch (error) {
+            logger?.warn?.('enrichment.all.provider.error', {
+                provider: providerName,
+                error: error instanceof Error ? error.message : String(error),
+            });
+            // Retry once after delay on transient errors
+            if (retryMs > 0) {
+                await new Promise((r) => setTimeout(r, retryMs));
+                try {
+                    raw = await provider(candidate);
+                    logger?.debug?.('enrichment.all.provider.retry.done', {
+                        provider: providerName,
+                        hasResult: !!raw,
+                    });
+                }
+                catch {
+                    raw = null;
+                }
+            }
+        }
+        // Deduct cost (even on failure - API was called)
+        if (stepCost > 0) {
+            remaining = Math.max(0, remaining - stepCost);
+            totalCost += stepCost;
+            if (onCost) {
+                try {
+                    await onCost(providerName, stepCost);
+                }
+                catch {
+                    // Ignore cost callback errors
+                }
+            }
+            logger?.debug?.('enrichment.all.cost.debit', {
+                provider: providerName,
+                cost: stepCost,
+                remaining,
+                totalCost,
+            });
+        }
+        // Process results
+        const now = new Date().toISOString();
+        if (isMultiResult(raw)) {
+            // Provider returned multiple emails
+            for (const emailResult of raw.emails) {
+                const emailLower = emailResult.email.toLowerCase();
+                if (seenEmails.has(emailLower)) {
+                    continue;
+                }
+                seenEmails.add(emailLower);
+                allEmails.push({
+                    email: emailResult.email,
+                    source: providerName,
+                    confidence: emailResult.confidence ?? 50,
+                    verified: emailResult.verified ?? false,
+                    type: classifyEmailType(emailResult.email),
+                    isCatchAll: emailResult.isCatchAll,
+                    foundAt: now,
+                    metadata: emailResult.metadata,
+                });
+            }
+        }
+        else if (raw?.email) {
+            // Provider returned single email
+            const emailLower = raw.email.toLowerCase();
+            if (!seenEmails.has(emailLower)) {
+                seenEmails.add(emailLower);
+                const confidence = typeof raw.score === 'number'
+                    ? raw.score
+                    : typeof raw.confidence === 'number'
+                        ? raw.confidence
+                        : 50;
+                allEmails.push({
+                    email: raw.email,
+                    source: providerName,
+                    confidence,
+                    verified: raw.verified ?? false,
+                    type: classifyEmailType(raw.email),
+                    foundAt: now,
+                });
+            }
+        }
+    }
+    // Sort by confidence (highest first), then by type (business first)
+    const typeOrder = {
+        business: 0,
+        unknown: 1,
+        role: 2,
+        personal: 3,
+        disposable: 4,
+    };
+    allEmails.sort((a, b) => {
+        // First by confidence (descending)
+        if (b.confidence !== a.confidence) {
+            return b.confidence - a.confidence;
+        }
+        // Then by type priority
+        return typeOrder[a.type] - typeOrder[b.type];
+    });
+    logger?.info?.('enrichment.all.complete', {
+        emailsFound: allEmails.length,
+        providersQueried: providersQueried.length,
+        totalCost,
+    });
+    return {
+        emails: allEmails,
+        candidate,
+        totalCost,
+        providersQueried,
+        completedAt: new Date().toISOString(),
+    };
+}
+/**
+ * Enrich multiple candidates and collect all emails (batch version)
+ */
+async function enrichAllBatch(candidates, options) {
+    const results = [];
+    const batchSize = options.batchSize ?? 50;
+    const delayMs = options.delayMs ?? 200;
+    for (let i = 0; i < candidates.length; i += batchSize) {
+        const chunk = candidates.slice(i, i + batchSize);
+        // Process batch in parallel
+        const batchResults = await Promise.all(chunk.map((candidate) => enrichAllEmails(candidate, options)));
+        results.push(...batchResults);
+        // Delay between batches to avoid rate limiting
+        if (i + batchSize < candidates.length && delayMs > 0) {
+            await new Promise((r) => setTimeout(r, delayMs));
+        }
+    }
+    return results;
+}

package/dist/enrichment/providers/apollo.d.ts

@@ -4,8 +4,8 @@
  * Apollo.io public API for email finding.
  * Uses mixed_people/search endpoint.
  */
-import type { EnrichmentCandidate, ProviderResult, ApolloConfig } from "../types";
+import type { EnrichmentCandidate, ProviderResult, ProviderMultiResult, ApolloConfig } from "../types";
 /**
  * Create the Apollo provider function
  */
-export declare function createApolloProvider(config: ApolloConfig): (candidate: EnrichmentCandidate) => Promise<ProviderResult | null>;
+export declare function createApolloProvider(config: ApolloConfig): (candidate: EnrichmentCandidate) => Promise<ProviderResult | ProviderMultiResult | null>;

package/dist/enrichment/providers/apollo.js

@@ -88,8 +88,8 @@ function createApolloProvider(config) {
     }
     async function fetchEmail(candidate) {
         const { name, org, domain } = extractInputs(candidate);
-        // Build request body
-        const body = { page: 1, per_page: 1 };
+        // Build request body - get more results for multi-email support
+        const body = { page: 1, per_page: 10 };
         if (truthy(name))
             body["q_person_name"] = String(name);
         if (truthy(domain))
@@ -112,19 +112,64 @@ function createApolloProvider(config) {
                 (json.people || json.matches || json.data?.people));
             if (!Array.isArray(people) || people.length === 0)
                 return null;
-            const p = people[0] || {};
-            const email = p.email ??
-                p.primary_email ??
-                p.emails?.[0]?.email ??
-                null;
-            if (!email)
+            // Collect all emails from all people
+            const emails = [];
+            const seenEmails = new Set();
+            for (const person of people) {
+                const p = person || {};
+                // Get primary email
+                const primaryEmail = p.email ??
+                    p.primary_email ??
+                    null;
+                if (primaryEmail) {
+                    const emailLower = primaryEmail.toLowerCase();
+                    if (!seenEmails.has(emailLower)) {
+                        seenEmails.add(emailLower);
+                        const score = typeof p.email_confidence === "number"
+                            ? p.email_confidence
+                            : Number(p.email_confidence ?? 0) || 50;
+                        const verified = mapVerified(p.email_status);
+                        emails.push({
+                            email: primaryEmail,
+                            verified,
+                            confidence: score,
+                            metadata: {
+                                name: p.name,
+                                title: p.title,
+                                company: p.organization?.name,
+                                linkedin: p.linkedin_url,
+                            },
+                        });
+                    }
+                }
+                // Also check emails array if present
+                const personEmails = p.emails;
+                if (Array.isArray(personEmails)) {
+                    for (const e of personEmails) {
+                        if (!e.email)
+                            continue;
+                        const emailLower = e.email.toLowerCase();
+                        if (seenEmails.has(emailLower))
+                            continue;
+                        seenEmails.add(emailLower);
+                        emails.push({
+                            email: e.email,
+                            verified: mapVerified(e.status),
+                            confidence: 50, // Secondary emails get lower confidence
+                            metadata: {
+                                name: p.name,
+                                title: p.title,
+                                company: p.organization?.name,
+                            },
+                        });
+                    }
+                }
+            }
+            if (emails.length === 0)
                 return null;
-            const score = typeof p.email_confidence === "number"
-                ? p.email_confidence
-                : Number(p.email_confidence ?? 0) || undefined;
-            const verified = mapVerified(p.email_status ??
-                p.emails?.[0]?.status);
-            return { email, verified, score };
+            // Sort by confidence
+            emails.sort((a, b) => (b.confidence ?? 0) - (a.confidence ?? 0));
+            return { emails };
         }
         catch {
             return null;

package/dist/enrichment/providers/construct.d.ts

@@ -4,8 +4,8 @@
  * Generates email pattern candidates based on name + domain, then verifies via MX check.
  * This is a FREE provider that doesn't require any API keys.
  */
-import type { EnrichmentCandidate, ProviderResult, ConstructConfig } from '../types';
+import type { EnrichmentCandidate, ProviderResult, ProviderMultiResult, ConstructConfig } from '../types';
 /**
  * Create the construct provider function
  */
-export declare function createConstructProvider(config?: ConstructConfig): (candidate: EnrichmentCandidate) => Promise<ProviderResult | null>;
+export declare function createConstructProvider(config?: ConstructConfig): (candidate: EnrichmentCandidate) => Promise<ProviderResult | ProviderMultiResult | null>;

package/dist/enrichment/providers/construct.js

@@ -88,18 +88,30 @@ function createConstructProvider(config) {
         }
         const candidates = buildCandidates({ first, last, domain });
         const max = Math.min(candidates.length, maxAttempts);
+        // Collect ALL valid email patterns (not just first match)
+        const validEmails = [];
         for (let i = 0; i < max; i++) {
             const email = candidates[i];
             const verification = await (0, mx_1.verifyEmailMx)(email, { timeoutMs });
             if (verification.valid === true && verification.confidence >= 50) {
-                return {
+                validEmails.push({
                     email,
                     verified: true,
-                    score: verification.confidence,
-                };
+                    confidence: verification.confidence,
+                    isCatchAll: verification.isCatchAll,
+                    metadata: {
+                        pattern: email.split('@')[0], // The local part pattern used
+                        mxRecords: verification.mxRecords,
+                    },
+                });
             }
         }
-        return null;
+        if (validEmails.length === 0) {
+            return null;
+        }
+        // Sort by confidence
+        validEmails.sort((a, b) => (b.confidence ?? 0) - (a.confidence ?? 0));
+        return { emails: validEmails };
     }
     // Mark provider name for orchestrator
     fetchEmail.__name = 'construct';

package/dist/enrichment/providers/hunter.d.ts

@@ -4,8 +4,8 @@
  * Hunter.io public API for email finding.
  * Uses email-finder endpoint with name+domain, falls back to domain-search.
  */
-import type { EnrichmentCandidate, ProviderResult, HunterConfig } from "../types";
+import type { EnrichmentCandidate, ProviderResult, ProviderMultiResult, HunterConfig } from "../types";
 /**
  * Create the Hunter provider function
  */
-export declare function createHunterProvider(config: HunterConfig): (candidate: EnrichmentCandidate) => Promise<ProviderResult | null>;
+export declare function createHunterProvider(config: HunterConfig): (candidate: EnrichmentCandidate) => Promise<ProviderResult | ProviderMultiResult | null>;

package/dist/enrichment/providers/hunter.js

@@ -97,6 +97,7 @@ function createHunterProvider(config) {
     async function fetchEmail(candidate) {
         const { first, last, domain } = extractInputs(candidate);
         let url = null;
+        let isEmailFinder = false;
         // Use email-finder if we have name components
         if (truthy(first) && truthy(last) && truthy(domain)) {
             const qs = new URLSearchParams({
@@ -106,13 +107,14 @@ function createHunterProvider(config) {
                 last_name: String(last),
             });
             url = `${API_BASE}/email-finder?${qs.toString()}`;
+            isEmailFinder = true;
         }
-        // Fall back to domain-search if only domain available
+        // Fall back to domain-search if only domain available (can return multiple)
         else if (truthy(domain)) {
             const qs = new URLSearchParams({
                 api_key: String(apiKey),
                 domain: String(domain),
-                limit: "1",
+                limit: "10", // Get more results
             });
             url = `${API_BASE}/domain-search?${qs.toString()}`;
         }
@@ -121,34 +123,58 @@ function createHunterProvider(config) {
         }
         try {
             const json = await requestWithRetry(url, 1, 100);
-            // Parse email-finder response shape
-            const ef = (json && (json.data || json.result));
-            if (ef && (ef.email || ef.score !== undefined)) {
-                const email = ef.email ?? null;
-                const score = typeof ef.score === "number"
-                    ? ef.score
-                    : Number(ef.score ?? 0) || undefined;
-                const verified = mapVerified(ef?.verification?.status ?? ef?.status);
-                if (!email)
-                    return null;
-                return { email, verified, score };
+            // Parse email-finder response shape (single result)
+            if (isEmailFinder) {
+                const ef = (json && (json.data || json.result));
+                if (ef && (ef.email || ef.score !== undefined)) {
+                    const email = ef.email ?? null;
+                    const score = typeof ef.score === "number"
+                        ? ef.score
+                        : Number(ef.score ?? 0) || undefined;
+                    const verified = mapVerified(ef?.verification?.status ?? ef?.status);
+                    if (!email)
+                        return null;
+                    return { email, verified, score };
+                }
             }
-            // Parse domain-search response shape
+            // Parse domain-search response shape (can have multiple emails)
             const ds = (json &&
                 json.data &&
                 Array.isArray(json.data.emails)
                 ? json.data.emails
                 : null);
             if (ds && ds.length > 0) {
-                const firstHit = ds[0];
-                const email = firstHit?.value || firstHit?.email || null;
-                const score = typeof firstHit?.confidence === "number"
-                    ? firstHit.confidence
-                    : Number(firstHit?.confidence ?? 0) || undefined;
-                const verified = mapVerified(firstHit?.verification?.status ?? firstHit?.status);
-                if (!email)
+                // Return all emails as multi-result
+                const emails = [];
+                const seenEmails = new Set();
+                for (const hit of ds) {
+                    const email = hit?.value || hit?.email;
+                    if (!email)
+                        continue;
+                    const emailLower = email.toLowerCase();
+                    if (seenEmails.has(emailLower))
+                        continue;
+                    seenEmails.add(emailLower);
+                    const score = typeof hit?.confidence === "number"
+                        ? hit.confidence
+                        : Number(hit?.confidence ?? 0) || 50;
+                    const verified = mapVerified(hit?.verification?.status ?? hit?.status);
+                    emails.push({
+                        email,
+                        verified,
+                        confidence: score,
+                        metadata: {
+                            firstName: hit.first_name,
+                            lastName: hit.last_name,
+                            position: hit.position,
+                        },
+                    });
+                }
+                if (emails.length === 0)
                     return null;
-                return { email, verified, score };
+                // Sort by confidence
+                emails.sort((a, b) => (b.confidence ?? 0) - (a.confidence ?? 0));
+                return { emails };
             }
             return null;
         }

package/dist/enrichment/providers/ldd.d.ts

@@ -3,9 +3,27 @@
  *
  * YOUR private database of ~500M scraped LinkedIn profiles with emails.
  * This is FREE and unlimited - it's your own service.
+ *
+ * IMPORTANT: Prefer numeric LinkedIn ID over username for lookups.
+ * The numeric ID (from objectUrn like "urn:li:member:307567") is STABLE and never changes,
+ * while usernames can be changed by users at any time.
  */
-import type { EnrichmentCandidate, ProviderResult, LddConfig } from "../types";
+import type { EnrichmentCandidate, ProviderResult, ProviderMultiResult, LddConfig } from "../types";
+/**
+ * Extract numeric LinkedIn ID from various formats:
+ * - Direct number: "307567"
+ * - URN format: "urn:li:member:307567"
+ * - Full URN: "urn:li:fs_salesProfile:(ACwAAAAEsW8B...,NAME_SEARCH,PJOV)"
+ * - objectUrn: "urn:li:member:307567"
+ *
+ * Returns the numeric ID as a string, or null if not found.
+ */
+export declare function extractNumericLinkedInId(input: string | undefined | null): string | null;
 /**
  * Create the LDD provider function
+ *
+ * Lookup priority:
+ * 1. Numeric LinkedIn ID (PREFERRED - stable, never changes)
+ * 2. Username (FALLBACK - can change over time)
  */
-export declare function createLddProvider(config: LddConfig): (candidate: EnrichmentCandidate) => Promise<ProviderResult | null>;
+export declare function createLddProvider(config: LddConfig): (candidate: EnrichmentCandidate) => Promise<ProviderResult | ProviderMultiResult | null>;