linkedin-secret-sauce 0.4.0 → 0.5.1

package/dist/enrichment/orchestrator.js

@@ -0,0 +1,218 @@
+"use strict";
+/**
+ * Email Enrichment Waterfall Orchestrator
+ *
+ * Runs providers in sequence until a verified email is found that meets
+ * the confidence threshold. Supports budget tracking and cost callbacks.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.enrichBusinessEmail = enrichBusinessEmail;
+exports.enrichBatch = enrichBatch;
+const personal_domains_1 = require("./utils/personal-domains");
+const disposable_domains_1 = require("./utils/disposable-domains");
+/**
+ * Default provider costs in USD per lookup
+ */
+const DEFAULT_PROVIDER_COSTS = {
+    construct: 0,
+    ldd: 0,
+    smartprospect: 0.01,
+    hunter: 0.005,
+    apollo: 0,
+    dropcontact: 0.01,
+};
+/**
+ * Normalize provider result to canonical format
+ */
+function normalizeProviderResult(providerName, raw) {
+    const iso = new Date().toISOString();
+    // No result from provider
+    if (!raw || !raw.email) {
+        return {
+            business_email: null,
+            business_email_source: providerName,
+            business_email_verified: false,
+            last_checked_at: iso,
+        };
+    }
+    const email = String(raw.email);
+    const confidence = typeof raw.score === 'number'
+        ? raw.score
+        : typeof raw.confidence === 'number'
+            ? raw.confidence
+            : undefined;
+    const verified = Boolean(raw.verified);
+    return {
+        business_email: email,
+        business_email_source: providerName,
+        business_email_verified: verified,
+        business_email_confidence: confidence,
+        last_checked_at: iso,
+    };
+}
+/**
+ * Get provider name from function
+ */
+function getProviderName(provider, index) {
+    return provider.__name ?? `provider-${index}`;
+}
+/**
+ * Get provider cost
+ */
+function getProviderCost(providerName) {
+    return DEFAULT_PROVIDER_COSTS[providerName] ?? 0;
+}
+/**
+ * Enrich a single candidate with business email
+ */
+async function enrichBusinessEmail(candidate, options) {
+    const { providers, maxCostPerEmail = Infinity, confidenceThreshold = 0, retryMs = 200, onCost, logger, } = options;
+    // Track remaining budget
+    let remaining = Number.isFinite(maxCostPerEmail) && maxCostPerEmail >= 0 ? maxCostPerEmail : Infinity;
+    logger?.debug?.('enrichment.start', {
+        providers: providers.length,
+        confidenceThreshold,
+        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.skip_budget', {
+                provider: providerName,
+                cost: stepCost,
+                remaining,
+            });
+            continue;
+        }
+        let raw = null;
+        try {
+            logger?.debug?.('enrichment.provider.start', { provider: providerName });
+            raw = await provider(candidate);
+            logger?.debug?.('enrichment.provider.done', {
+                provider: providerName,
+                hasResult: !!raw?.email,
+            });
+        }
+        catch (error) {
+            logger?.warn?.('enrichment.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.provider.retry.done', {
+                        provider: providerName,
+                        hasResult: !!raw?.email,
+                    });
+                }
+                catch {
+                    raw = null;
+                }
+            }
+        }
+        // Deduct cost (even on failure - API was called)
+        if (stepCost > 0) {
+            remaining = Math.max(0, remaining - stepCost);
+            if (onCost) {
+                try {
+                    await onCost(providerName, stepCost);
+                }
+                catch {
+                    // Ignore cost callback errors
+                }
+            }
+            logger?.debug?.('enrichment.cost.debit', {
+                provider: providerName,
+                cost: stepCost,
+                remaining,
+            });
+        }
+        // Normalize result
+        const normalized = normalizeProviderResult(providerName, raw);
+        // Skip if no email found
+        if (!normalized.business_email) {
+            continue;
+        }
+        // Filter out personal emails
+        if ((0, personal_domains_1.isPersonalEmail)(normalized.business_email)) {
+            logger?.debug?.('enrichment.skip_personal', {
+                provider: providerName,
+                email: normalized.business_email,
+            });
+            continue;
+        }
+        // Filter out disposable emails
+        if ((0, disposable_domains_1.isDisposableEmail)(normalized.business_email)) {
+            logger?.debug?.('enrichment.skip_disposable', {
+                provider: providerName,
+                email: normalized.business_email,
+            });
+            continue;
+        }
+        // Check confidence threshold
+        const score = normalized.business_email_confidence;
+        if (confidenceThreshold > 0 && score !== undefined && score < confidenceThreshold) {
+            logger?.debug?.('enrichment.skip_low_confidence', {
+                provider: providerName,
+                score,
+                threshold: confidenceThreshold,
+            });
+            continue;
+        }
+        // Check if verified
+        if (!normalized.business_email_verified) {
+            logger?.debug?.('enrichment.skip_unverified', {
+                provider: providerName,
+                email: normalized.business_email,
+            });
+            continue;
+        }
+        // Success!
+        logger?.info?.('enrichment.success', {
+            provider: providerName,
+            email: normalized.business_email,
+            confidence: normalized.business_email_confidence,
+        });
+        return normalized;
+    }
+    // No provider found a valid email
+    logger?.debug?.('enrichment.not_found', {
+        candidateHasName: !!(candidate.firstName || candidate.name),
+        candidateHasDomain: !!(candidate.domain || candidate.company),
+    });
+    return {
+        business_email: null,
+        business_email_source: null,
+        business_email_verified: false,
+        last_checked_at: new Date().toISOString(),
+        status: 'not_found',
+    };
+}
+/**
+ * Enrich multiple candidates in batches
+ */
+async function enrichBatch(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) => enrichBusinessEmail(candidate, options)));
+        // Combine results with candidates
+        batchResults.forEach((result, idx) => {
+            results.push({ candidate: chunk[idx], ...result });
+        });
+        // 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

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

package/dist/enrichment/providers/apollo.js

@@ -0,0 +1,136 @@
+"use strict";
+/**
+ * Apollo.io Provider
+ *
+ * Apollo.io public API for email finding.
+ * Uses mixed_people/search endpoint.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createApolloProvider = createApolloProvider;
+const API_BASE = "https://api.apollo.io/v1";
+/**
+ * Delay helper for retry logic
+ */
+async function delay(ms) {
+    return new Promise((r) => setTimeout(r, ms));
+}
+/**
+ * Check if value is truthy
+ */
+function truthy(v) {
+    return v !== undefined && v !== null && String(v).length > 0;
+}
+/**
+ * Map Apollo verification status to boolean
+ */
+function mapVerified(status) {
+    if (!status)
+        return undefined;
+    const s = String(status).toLowerCase();
+    if (s === "verified" || s === "deliverable")
+        return true;
+    if (s === "invalid" || s === "undeliverable")
+        return false;
+    return undefined;
+}
+/**
+ * HTTP request with retry on 429 rate limit
+ */
+async function requestWithRetry(url, init, retries = 1, backoffMs = 200) {
+    let lastErr;
+    for (let i = 0; i <= retries; i++) {
+        try {
+            const res = await fetch(url, init);
+            // Retry on rate limit
+            if (res?.status === 429 && i < retries) {
+                await delay(backoffMs * Math.pow(2, i));
+                continue;
+            }
+            if (!res || res.status >= 400) {
+                lastErr = new Error(`apollo_http_${res?.status ?? "error"}`);
+                break;
+            }
+            const json = (await res.json());
+            return json;
+        }
+        catch (err) {
+            lastErr = err;
+            if (i < retries) {
+                await delay(backoffMs * Math.pow(2, i));
+                continue;
+            }
+        }
+    }
+    throw lastErr ?? new Error("apollo_http_error");
+}
+/**
+ * Extract inputs from candidate
+ */
+function extractInputs(candidate) {
+    const name = candidate.name || candidate.full_name || candidate.fullName || undefined;
+    const org = candidate.company || candidate.organization || candidate.org || undefined;
+    const domain = candidate.domain ||
+        candidate.companyDomain ||
+        candidate.company_domain ||
+        undefined;
+    return { name, org, domain };
+}
+/**
+ * Create the Apollo provider function
+ */
+function createApolloProvider(config) {
+    const { apiKey } = config;
+    if (!apiKey) {
+        // Return a no-op provider if not configured
+        const noopProvider = async () => null;
+        noopProvider.__name = "apollo";
+        return noopProvider;
+    }
+    async function fetchEmail(candidate) {
+        const { name, org, domain } = extractInputs(candidate);
+        // Build request body
+        const body = { page: 1, per_page: 1 };
+        if (truthy(name))
+            body["q_person_name"] = String(name);
+        if (truthy(domain))
+            body["organization_domains"] = [String(domain)];
+        else if (truthy(org))
+            body["q_organization_name"] = String(org);
+        const url = `${API_BASE}/mixed_people/search`;
+        const init = {
+            method: "POST",
+            headers: {
+                "content-type": "application/json",
+                "X-Api-Key": String(apiKey),
+            },
+            body: JSON.stringify(body),
+        };
+        try {
+            const json = await requestWithRetry(url, init, 1, 100);
+            // Parse response - handle multiple possible shapes
+            const people = (json &&
+                (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)
+                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 };
+        }
+        catch {
+            return null;
+        }
+    }
+    // Mark provider name for orchestrator
+    fetchEmail.__name = "apollo";
+    return fetchEmail;
+}

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

@@ -0,0 +1,11 @@
+/**
+ * Email Construction Provider
+ *
+ * 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';
+/**
+ * Create the construct provider function
+ */
+export declare function createConstructProvider(config?: ConstructConfig): (candidate: EnrichmentCandidate) => Promise<ProviderResult | null>;

package/dist/enrichment/providers/construct.js

@@ -0,0 +1,107 @@
+"use strict";
+/**
+ * Email Construction Provider
+ *
+ * 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.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createConstructProvider = createConstructProvider;
+const mx_1 = require("../verification/mx");
+const personal_domains_1 = require("../utils/personal-domains");
+const validation_1 = require("../utils/validation");
+/**
+ * Build all email pattern candidates for a person
+ */
+function buildCandidates(input) {
+    const domain = String(input.domain || '').toLowerCase();
+    const first = (0, validation_1.cleanNamePart)(input.first || '');
+    const last = (0, validation_1.cleanNamePart)(input.last || '');
+    const fl = first ? first[0] : '';
+    const locals = [];
+    // Patterns with both first and last name
+    if (first && last) {
+        locals.push(`${first}.${last}`); // john.doe
+        locals.push(`${fl}.${last}`); // j.doe
+        locals.push(`${first}${last[0] ?? ''}`); // johnd
+        locals.push(`${fl}${last}`); // jdoe
+        locals.push(`${first}_${last}`); // john_doe
+        locals.push(`${last}.${first}`); // doe.john
+    }
+    // Single name patterns
+    if (first)
+        locals.push(first); // john
+    if (last)
+        locals.push(last); // doe
+    // Deduplicate while preserving order
+    const seen = new Set();
+    const emails = [];
+    for (const local of locals) {
+        if (!local)
+            continue;
+        const email = `${local}@${domain}`;
+        if (!seen.has(email)) {
+            seen.add(email);
+            emails.push(email);
+        }
+    }
+    return emails;
+}
+/**
+ * Extract name components from candidate
+ */
+function extractNames(candidate) {
+    const firstName = candidate.firstName ||
+        candidate.first_name ||
+        candidate.first ||
+        candidate.name?.split(' ')?.[0] ||
+        '';
+    const lastName = candidate.lastName ||
+        candidate.last_name ||
+        candidate.last ||
+        candidate.name?.split(' ')?.slice(1).join(' ') ||
+        '';
+    return { first: firstName, last: lastName };
+}
+/**
+ * Extract domain from candidate
+ */
+function extractDomain(candidate) {
+    return candidate.domain || candidate.companyDomain || candidate.company_domain || '';
+}
+/**
+ * Create the construct provider function
+ */
+function createConstructProvider(config) {
+    const maxAttempts = config?.maxAttempts ?? 8;
+    const timeoutMs = config?.timeoutMs ?? 5000;
+    async function fetchEmail(candidate) {
+        const { first, last } = extractNames(candidate);
+        const domain = extractDomain(candidate);
+        // Skip if missing required fields
+        if (!first || !domain) {
+            return null;
+        }
+        // Skip personal domains
+        if ((0, personal_domains_1.isPersonalDomain)(domain)) {
+            return null;
+        }
+        const candidates = buildCandidates({ first, last, domain });
+        const max = Math.min(candidates.length, maxAttempts);
+        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 {
+                    email,
+                    verified: true,
+                    score: verification.confidence,
+                };
+            }
+        }
+        return null;
+    }
+    // Mark provider name for orchestrator
+    fetchEmail.__name = 'construct';
+    return fetchEmail;
+}

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

@@ -0,0 +1,16 @@
+/**
+ * Dropcontact Provider
+ *
+ * Dropcontact API for email finding.
+ * This is a placeholder implementation - full implementation would call the Dropcontact API.
+ */
+import type { EnrichmentCandidate, ProviderResult, DropcontactConfig } from '../types';
+/**
+ * Create the Dropcontact provider function
+ *
+ * Note: This is a placeholder. Full implementation would:
+ * 1. POST to https://api.dropcontact.io/batch with contacts
+ * 2. Poll for results
+ * 3. Return enriched email with verification status
+ */
+export declare function createDropcontactProvider(config: DropcontactConfig): (_candidate: EnrichmentCandidate) => Promise<ProviderResult | null>;

package/dist/enrichment/providers/dropcontact.js

@@ -0,0 +1,37 @@
+"use strict";
+/**
+ * Dropcontact Provider
+ *
+ * Dropcontact API for email finding.
+ * This is a placeholder implementation - full implementation would call the Dropcontact API.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createDropcontactProvider = createDropcontactProvider;
+/**
+ * Create the Dropcontact provider function
+ *
+ * Note: This is a placeholder. Full implementation would:
+ * 1. POST to https://api.dropcontact.io/batch with contacts
+ * 2. Poll for results
+ * 3. Return enriched email with verification status
+ */
+function createDropcontactProvider(config) {
+    const { apiKey } = config;
+    if (!apiKey) {
+        // Return a no-op provider if not configured
+        const noopProvider = async () => null;
+        noopProvider.__name = 'dropcontact';
+        return noopProvider;
+    }
+    async function fetchEmail(_candidate) {
+        // TODO: Implement Dropcontact API integration
+        // API: POST https://api.dropcontact.io/batch
+        // Headers: X-Access-Token: {apiKey}
+        // Body: { data: [{ first_name, last_name, company, website }], siren: false, language: "en" }
+        // For now, return null (skip this provider)
+        return null;
+    }
+    // Mark provider name for orchestrator
+    fetchEmail.__name = 'dropcontact';
+    return fetchEmail;
+}

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

@@ -0,0 +1,11 @@
+/**
+ * Hunter.io Provider
+ *
+ * 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";
+/**
+ * Create the Hunter provider function
+ */
+export declare function createHunterProvider(config: HunterConfig): (candidate: EnrichmentCandidate) => Promise<ProviderResult | null>;