linkedin-secret-sauce 0.4.0 → 0.5.1

package/dist/enrichment/providers/hunter.js

@@ -0,0 +1,162 @@
+"use strict";
+/**
+ * Hunter.io Provider
+ *
+ * Hunter.io public API for email finding.
+ * Uses email-finder endpoint with name+domain, falls back to domain-search.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createHunterProvider = createHunterProvider;
+const API_BASE = "https://api.hunter.io/v2";
+/**
+ * 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 Hunter verification status to boolean
+ */
+function mapVerified(status) {
+    if (!status)
+        return undefined;
+    const s = String(status).toLowerCase();
+    if (s === "valid" || s === "deliverable")
+        return true;
+    if (s === "invalid" || s === "undeliverable")
+        return false;
+    return undefined; // catch-all/unknown/webmail -> leave undefined
+}
+/**
+ * HTTP request with retry on 429 rate limit
+ */
+async function requestWithRetry(url, retries = 1, backoffMs = 200) {
+    let lastErr;
+    for (let i = 0; i <= retries; i++) {
+        try {
+            const res = await fetch(url);
+            // 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(`hunter_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("hunter_http_error");
+}
+/**
+ * Extract name and domain from candidate
+ */
+function extractInputs(candidate) {
+    const name = candidate.name || candidate.fullName || candidate.full_name;
+    const first = candidate.first ||
+        candidate.first_name ||
+        candidate.firstName ||
+        name?.split?.(" ")?.[0];
+    const last = candidate.last ||
+        candidate.last_name ||
+        candidate.lastName ||
+        name?.split?.(" ")?.slice(1).join(" ") ||
+        undefined;
+    const domain = candidate.domain ||
+        candidate.companyDomain ||
+        candidate.company_domain ||
+        undefined;
+    return { first, last, domain };
+}
+/**
+ * Create the Hunter provider function
+ */
+function createHunterProvider(config) {
+    const { apiKey } = config;
+    if (!apiKey) {
+        // Return a no-op provider if not configured
+        const noopProvider = async () => null;
+        noopProvider.__name = "hunter";
+        return noopProvider;
+    }
+    async function fetchEmail(candidate) {
+        const { first, last, domain } = extractInputs(candidate);
+        let url = null;
+        // Use email-finder if we have name components
+        if (truthy(first) && truthy(last) && truthy(domain)) {
+            const qs = new URLSearchParams({
+                api_key: String(apiKey),
+                domain: String(domain),
+                first_name: String(first),
+                last_name: String(last),
+            });
+            url = `${API_BASE}/email-finder?${qs.toString()}`;
+        }
+        // Fall back to domain-search if only domain available
+        else if (truthy(domain)) {
+            const qs = new URLSearchParams({
+                api_key: String(apiKey),
+                domain: String(domain),
+                limit: "1",
+            });
+            url = `${API_BASE}/domain-search?${qs.toString()}`;
+        }
+        else {
+            return null; // Can't search without domain
+        }
+        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 domain-search response shape
+            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 null;
+                return { email, verified, score };
+            }
+            return null;
+        }
+        catch {
+            return null;
+        }
+    }
+    // Mark provider name for orchestrator
+    fetchEmail.__name = "hunter";
+    return fetchEmail;
+}

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

@@ -0,0 +1,9 @@
+/**
+ * Email Enrichment Providers
+ */
+export { createConstructProvider } from './construct';
+export { createLddProvider } from './ldd';
+export { createSmartProspectProvider } from './smartprospect';
+export { createHunterProvider } from './hunter';
+export { createApolloProvider } from './apollo';
+export { createDropcontactProvider } from './dropcontact';

package/dist/enrichment/providers/index.js

@@ -0,0 +1,18 @@
+"use strict";
+/**
+ * Email Enrichment Providers
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createDropcontactProvider = exports.createApolloProvider = exports.createHunterProvider = exports.createSmartProspectProvider = exports.createLddProvider = exports.createConstructProvider = void 0;
+var construct_1 = require("./construct");
+Object.defineProperty(exports, "createConstructProvider", { enumerable: true, get: function () { return construct_1.createConstructProvider; } });
+var ldd_1 = require("./ldd");
+Object.defineProperty(exports, "createLddProvider", { enumerable: true, get: function () { return ldd_1.createLddProvider; } });
+var smartprospect_1 = require("./smartprospect");
+Object.defineProperty(exports, "createSmartProspectProvider", { enumerable: true, get: function () { return smartprospect_1.createSmartProspectProvider; } });
+var hunter_1 = require("./hunter");
+Object.defineProperty(exports, "createHunterProvider", { enumerable: true, get: function () { return hunter_1.createHunterProvider; } });
+var apollo_1 = require("./apollo");
+Object.defineProperty(exports, "createApolloProvider", { enumerable: true, get: function () { return apollo_1.createApolloProvider; } });
+var dropcontact_1 = require("./dropcontact");
+Object.defineProperty(exports, "createDropcontactProvider", { enumerable: true, get: function () { return dropcontact_1.createDropcontactProvider; } });

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

@@ -0,0 +1,11 @@
+/**
+ * LinkedIn Data Dump (LDD) Provider
+ *
+ * YOUR private database of ~500M scraped LinkedIn profiles with emails.
+ * This is FREE and unlimited - it's your own service.
+ */
+import type { EnrichmentCandidate, ProviderResult, LddConfig } from "../types";
+/**
+ * Create the LDD provider function
+ */
+export declare function createLddProvider(config: LddConfig): (candidate: EnrichmentCandidate) => Promise<ProviderResult | null>;

package/dist/enrichment/providers/ldd.js

@@ -0,0 +1,110 @@
+"use strict";
+/**
+ * LinkedIn Data Dump (LDD) Provider
+ *
+ * YOUR private database of ~500M scraped LinkedIn profiles with emails.
+ * This is FREE and unlimited - it's your own service.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createLddProvider = createLddProvider;
+const validation_1 = require("../utils/validation");
+/**
+ * Delay helper for retry logic
+ */
+async function delay(ms) {
+    return new Promise((r) => setTimeout(r, ms));
+}
+/**
+ * HTTP request with retry on 429 rate limit
+ */
+async function requestWithRetry(url, token, retries = 1, backoffMs = 200) {
+    let lastErr;
+    for (let i = 0; i <= retries; i++) {
+        try {
+            const res = await fetch(url, {
+                method: "GET",
+                headers: {
+                    Authorization: `Bearer ${token}`,
+                    "Content-Type": "application/json",
+                },
+            });
+            // Retry on rate limit
+            if (res?.status === 429 && i < retries) {
+                await delay(backoffMs * Math.pow(2, i));
+                continue;
+            }
+            return res;
+        }
+        catch (err) {
+            lastErr = err;
+            if (i < retries) {
+                await delay(backoffMs * Math.pow(2, i));
+                continue;
+            }
+        }
+    }
+    throw lastErr ?? new Error("ldd_http_error");
+}
+/**
+ * Extract LinkedIn username from candidate
+ */
+function extractUsername(candidate) {
+    // Direct username
+    const directUsername = candidate.linkedinUsername || candidate.linkedin_username;
+    if (directUsername)
+        return directUsername;
+    // Extract from URL
+    const url = candidate.linkedinUrl || candidate.linkedin_url;
+    if (url) {
+        const extracted = (0, validation_1.extractLinkedInUsername)(url);
+        if (extracted)
+            return extracted;
+    }
+    return null;
+}
+/**
+ * Create the LDD provider function
+ */
+function createLddProvider(config) {
+    const { apiUrl, apiToken } = config;
+    if (!apiUrl || !apiToken) {
+        // Return a no-op provider if not configured
+        const noopProvider = async () => null;
+        noopProvider.__name = "ldd";
+        return noopProvider;
+    }
+    async function fetchEmail(candidate) {
+        const username = extractUsername(candidate);
+        if (!username) {
+            return null;
+        }
+        try {
+            const endpoint = `${apiUrl}/api/v1/profiles/by-username/${encodeURIComponent(username)}`;
+            const response = await requestWithRetry(endpoint, apiToken, 1, 100);
+            if (!response.ok) {
+                return null;
+            }
+            const data = (await response.json());
+            if (!data.success || !data.data) {
+                return null;
+            }
+            // Find first valid email
+            const emails = data.data.emails || [];
+            const validEmail = emails.find((e) => e.email_address && e.email_address.includes("@"));
+            if (!validEmail) {
+                return null;
+            }
+            return {
+                email: validEmail.email_address,
+                verified: true, // LDD data is pre-verified
+                score: 90, // High confidence from your own database
+            };
+        }
+        catch {
+            return null;
+        }
+    }
+    // Mark provider name for orchestrator
+    fetchEmail.__name = "ldd";
+    return fetchEmail;
+}

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

@@ -0,0 +1,19 @@
+/**
+ * SmartProspect/Smartlead Provider
+ *
+ * Smartlead's prospect database - a REVERSE-ENGINEERED private API.
+ * Two-phase process: search (free) then fetch (costs credits).
+ *
+ * Supports two authentication methods:
+ * 1. Direct token: Pass `apiToken` directly (for pre-authenticated scenarios)
+ * 2. Credentials: Pass `email` and `password` for automatic login with token caching
+ */
+import type { EnrichmentCandidate, ProviderResult, SmartProspectConfig } from "../types";
+/**
+ * Create the SmartProspect provider function
+ *
+ * Supports two auth methods:
+ * 1. Direct token: Pass `apiToken` in config
+ * 2. Credentials: Pass `email` and `password` in config for auto-login
+ */
+export declare function createSmartProspectProvider(config: SmartProspectConfig): (candidate: EnrichmentCandidate) => Promise<ProviderResult | null>;

package/dist/enrichment/providers/smartprospect.js

@@ -0,0 +1,333 @@
+"use strict";
+/**
+ * SmartProspect/Smartlead Provider
+ *
+ * Smartlead's prospect database - a REVERSE-ENGINEERED private API.
+ * Two-phase process: search (free) then fetch (costs credits).
+ *
+ * Supports two authentication methods:
+ * 1. Direct token: Pass `apiToken` directly (for pre-authenticated scenarios)
+ * 2. Credentials: Pass `email` and `password` for automatic login with token caching
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createSmartProspectProvider = createSmartProspectProvider;
+const smartlead_auth_1 = require("../auth/smartlead-auth");
+const DEFAULT_API_URL = "https://prospect-api.smartlead.ai/api/search-email-leads";
+/**
+ * Delay helper for retry logic
+ */
+async function delay(ms) {
+    return new Promise((r) => setTimeout(r, ms));
+}
+/**
+ * HTTP request with retry on 429 rate limit
+ */
+async function requestWithRetry(url, options, retries = 2, backoffMs = 300) {
+    let lastErr;
+    for (let i = 0; i <= retries; i++) {
+        try {
+            const res = await fetch(url, options);
+            // Retry on rate limit
+            if (res.status === 429 && i < retries) {
+                await delay(backoffMs * Math.pow(2, i));
+                continue;
+            }
+            if (!res.ok) {
+                const errorText = await res.text().catch(() => "");
+                throw new Error(`SmartProspect API error: ${res.status} - ${errorText}`);
+            }
+            return (await res.json());
+        }
+        catch (err) {
+            lastErr = err;
+            if (i < retries) {
+                await delay(backoffMs * Math.pow(2, i));
+                continue;
+            }
+        }
+    }
+    throw lastErr ?? new Error("smartprospect_http_error");
+}
+/**
+ * Calculate match score between search input and contact result
+ */
+function calculateMatchScore(contact, searchName, company, title) {
+    let score = 0;
+    // Name match scoring (0-50 points)
+    const contactName = contact.fullName?.toLowerCase() || "";
+    const searchNameLower = searchName.toLowerCase();
+    if (contactName === searchNameLower) {
+        score += 50; // Exact match
+    }
+    else if (contactName.includes(searchNameLower) ||
+        searchNameLower.includes(contactName)) {
+        score += 30; // Partial match
+    }
+    // Company match scoring (0-30 points)
+    if (company) {
+        const contactCompany = contact.company?.name?.toLowerCase() || "";
+        const searchCompany = company.toLowerCase();
+        if (contactCompany === searchCompany) {
+            score += 30; // Exact match
+        }
+        else if (contactCompany.includes(searchCompany) ||
+            searchCompany.includes(contactCompany)) {
+            score += 15; // Partial match
+        }
+    }
+    // Title match scoring (0-10 points)
+    if (title) {
+        const contactTitle = contact.title?.toLowerCase() || "";
+        const searchTitle = title.toLowerCase();
+        if (contactTitle.includes(searchTitle) ||
+            searchTitle.includes(contactTitle)) {
+            score += 10;
+        }
+    }
+    // Deliverability score bonus (0-10 points)
+    if (contact.emailDeliverability > 0) {
+        score += contact.emailDeliverability * 10;
+    }
+    return score;
+}
+/**
+ * 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 { firstName, lastName };
+}
+/**
+ * Create the SmartProspect provider function
+ *
+ * Supports two auth methods:
+ * 1. Direct token: Pass `apiToken` in config
+ * 2. Credentials: Pass `email` and `password` in config for auto-login
+ */
+function createSmartProspectProvider(config) {
+    const { apiToken, email, password, apiUrl = DEFAULT_API_URL, loginUrl, eagerInit = true, } = config;
+    // Check if we have valid auth config
+    const hasDirectToken = !!apiToken;
+    const hasCredentials = !!email && !!password;
+    if (!hasDirectToken && !hasCredentials) {
+        // Return a no-op provider if not configured
+        const noopProvider = async () => null;
+        noopProvider.__name = "smartprospect";
+        return noopProvider;
+    }
+    /**
+     * Get the current auth token (either direct or via login)
+     */
+    async function getAuthToken() {
+        if (hasDirectToken) {
+            return apiToken;
+        }
+        // Use credentials-based auth with token caching
+        return (0, smartlead_auth_1.getSmartLeadToken)({
+            credentials: { email: email, password: password },
+            loginUrl,
+        });
+    }
+    // Eager initialization: pre-fetch token so it's ready for first request
+    if (eagerInit && hasCredentials) {
+        // Fire and forget - don't block provider creation
+        getAuthToken().catch(() => {
+            // Silently ignore errors during eager init - will retry on first request
+        });
+    }
+    /**
+     * Handle 401 errors by clearing cached token
+     */
+    async function handleAuthError() {
+        if (hasCredentials) {
+            (0, smartlead_auth_1.clearSmartLeadToken)(email);
+        }
+    }
+    /**
+     * Search for contacts matching filters (FREE - no credits used)
+     */
+    async function searchContacts(filters) {
+        const makeRequest = async (token) => {
+            return requestWithRetry(`${apiUrl}/search-contacts`, {
+                method: "POST",
+                headers: {
+                    Authorization: `Bearer ${token}`,
+                    "Content-Type": "application/json",
+                    Accept: "application/json",
+                },
+                body: JSON.stringify({
+                    ...filters,
+                    dontDisplayOwnedContact: filters.dontDisplayOwnedContact ?? true,
+                    limit: filters.limit ?? 10,
+                    titleExactMatch: filters.titleExactMatch ?? false,
+                }),
+            });
+        };
+        try {
+            const token = await getAuthToken();
+            return await makeRequest(token);
+        }
+        catch (err) {
+            // On 401, clear token and retry once with fresh token
+            if (err instanceof Error &&
+                err.message.includes("401") &&
+                hasCredentials) {
+                await handleAuthError();
+                try {
+                    const freshToken = await getAuthToken();
+                    return await makeRequest(freshToken);
+                }
+                catch {
+                    // Retry failed too
+                }
+            }
+            return {
+                success: false,
+                message: "Search failed",
+                data: { list: [], total_count: 0 },
+            };
+        }
+    }
+    /**
+     * Fetch/enrich emails for specific contact IDs (COSTS CREDITS)
+     */
+    async function fetchContacts(contactIds) {
+        const makeRequest = async (token) => {
+            return requestWithRetry(`${apiUrl}/fetch-contacts`, {
+                method: "POST",
+                headers: {
+                    Authorization: `Bearer ${token}`,
+                    "Content-Type": "application/json",
+                    Accept: "application/json",
+                },
+                body: JSON.stringify({ contactIds }),
+            });
+        };
+        try {
+            const token = await getAuthToken();
+            return await makeRequest(token);
+        }
+        catch (err) {
+            // On 401, clear token and retry once with fresh token
+            if (err instanceof Error &&
+                err.message.includes("401") &&
+                hasCredentials) {
+                await handleAuthError();
+                try {
+                    const freshToken = await getAuthToken();
+                    return await makeRequest(freshToken);
+                }
+                catch {
+                    // Retry failed too
+                }
+            }
+            return {
+                success: false,
+                message: "Fetch failed",
+                data: {
+                    list: [],
+                    total_count: 0,
+                    metrics: {
+                        totalContacts: 0,
+                        totalEmails: 0,
+                        noEmailFound: 0,
+                        invalidEmails: 0,
+                        catchAllEmails: 0,
+                        verifiedEmails: 0,
+                        completed: 0,
+                    },
+                    leads_found: 0,
+                    email_fetched: 0,
+                    verification_status_list: [],
+                },
+            };
+        }
+    }
+    async function fetchEmail(candidate) {
+        const { firstName, lastName } = extractNames(candidate);
+        if (!firstName) {
+            return null; // Minimum requirement
+        }
+        const fullName = `${firstName} ${lastName}`.trim();
+        const company = candidate.company ||
+            candidate.currentCompany ||
+            candidate.organization ||
+            undefined;
+        const title = candidate.title ||
+            candidate.currentRole ||
+            candidate.current_role ||
+            undefined;
+        const domain = candidate.domain ||
+            candidate.companyDomain ||
+            candidate.company_domain ||
+            undefined;
+        // Build search filters
+        const filters = {
+            name: [fullName],
+            limit: 5, // Get top 5 to find best match
+        };
+        if (company) {
+            filters.company = [company];
+        }
+        if (domain) {
+            filters.domain = [domain];
+        }
+        // Step 1: Search for contacts (FREE)
+        const searchResult = await searchContacts(filters);
+        if (!searchResult.success || searchResult.data.list.length === 0) {
+            return null;
+        }
+        // Find best match by scoring
+        const matches = searchResult.data.list;
+        let bestMatch = null;
+        let bestScore = 0;
+        for (const contact of matches) {
+            const score = calculateMatchScore(contact, fullName, company, title);
+            if (score > bestScore) {
+                bestScore = score;
+                bestMatch = contact;
+            }
+        }
+        if (!bestMatch) {
+            return null;
+        }
+        // Step 2: Fetch email for best match (COSTS CREDITS)
+        const fetchResult = await fetchContacts([bestMatch.id]);
+        if (!fetchResult.success || fetchResult.data.list.length === 0) {
+            return null;
+        }
+        const enrichedContact = fetchResult.data.list[0];
+        const email = enrichedContact?.email;
+        if (!email) {
+            return null;
+        }
+        // Calculate verification confidence
+        const isVerified = enrichedContact.verificationStatus === "valid";
+        const isCatchAll = enrichedContact.verificationStatus === "catch_all";
+        const deliverability = enrichedContact.emailDeliverability || 0;
+        let confidence = deliverability * 100;
+        if (isVerified) {
+            confidence = Math.max(confidence, 90);
+        }
+        else if (isCatchAll) {
+            confidence = Math.min(confidence, 75);
+        }
+        return {
+            email,
+            verified: isVerified || isCatchAll, // Accept catch-all as semi-verified
+            score: confidence,
+        };
+    }
+    // Mark provider name for orchestrator
+    fetchEmail.__name = "smartprospect";
+    return fetchEmail;
+}