linkedin-secret-sauce 0.5.1 → 0.7.1

package/dist/enrichment/providers/smartprospect.js

@@ -8,9 +8,14 @@
  * 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
+ *
+ * Exports:
+ * - createSmartProspectProvider: For email enrichment (waterfall pattern)
+ * - createSmartProspectClient: Full client with search/fetch capabilities
  */
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.createSmartProspectProvider = createSmartProspectProvider;
+exports.createSmartProspectClient = createSmartProspectClient;
 const smartlead_auth_1 = require("../auth/smartlead-auth");
 const DEFAULT_API_URL = "https://prospect-api.smartlead.ai/api/search-email-leads";
 /**
@@ -19,6 +24,12 @@ const DEFAULT_API_URL = "https://prospect-api.smartlead.ai/api/search-email-lead
 async function delay(ms) {
     return new Promise((r) => setTimeout(r, ms));
 }
+const DEFAULT_POLLING_CONFIG = {
+    initialDelay: 500,
+    pollInterval: 1000,
+    maxAttempts: 10,
+    maxWaitTime: 15000,
+};
 /**
  * HTTP request with retry on 429 rate limit
  */
@@ -197,11 +208,85 @@ function createSmartProspectProvider(config) {
             };
         }
     }
+    /**
+     * Poll get-contacts until email lookup is complete (provider version)
+     */
+    async function pollForContactResults(filterId, expectedCount) {
+        const { initialDelay, pollInterval, maxAttempts, maxWaitTime } = DEFAULT_POLLING_CONFIG;
+        const startTime = Date.now();
+        await delay(initialDelay);
+        const makeRequest = async (token) => {
+            return requestWithRetry(`${apiUrl}/get-contacts`, {
+                method: "POST",
+                headers: {
+                    Authorization: `Bearer ${token}`,
+                    "Content-Type": "application/json",
+                    Accept: "application/json",
+                },
+                body: JSON.stringify({
+                    filter_id: filterId,
+                    limit: expectedCount,
+                    offset: 0,
+                }),
+            });
+        };
+        for (let attempt = 0; attempt < maxAttempts; attempt++) {
+            if (Date.now() - startTime > maxWaitTime) {
+                break;
+            }
+            try {
+                const token = await getAuthToken();
+                const result = await makeRequest(token);
+                if (result.success && result.data.metrics) {
+                    const { completed, totalContacts } = result.data.metrics;
+                    if (completed >= totalContacts || completed >= expectedCount) {
+                        return result;
+                    }
+                }
+                await delay(pollInterval);
+            }
+            catch (err) {
+                if (err instanceof Error && err.message.includes("401") && hasCredentials) {
+                    await handleAuthError();
+                }
+                await delay(pollInterval);
+            }
+        }
+        // Return last result
+        try {
+            const token = await getAuthToken();
+            return await makeRequest(token);
+        }
+        catch {
+            return {
+                success: false,
+                message: "Polling timed out",
+                data: {
+                    list: [],
+                    total_count: 0,
+                    metrics: {
+                        totalContacts: 0,
+                        totalEmails: 0,
+                        noEmailFound: 0,
+                        invalidEmails: 0,
+                        catchAllEmails: 0,
+                        verifiedEmails: 0,
+                        completed: 0,
+                    },
+                },
+            };
+        }
+    }
     /**
      * Fetch/enrich emails for specific contact IDs (COSTS CREDITS)
+     *
+     * Uses async polling pattern:
+     * 1. Call fetch-contacts (returns immediately with status: "pending")
+     * 2. Poll get-contacts until completed
+     * 3. Return enriched contacts with emails
      */
     async function fetchContacts(contactIds) {
-        const makeRequest = async (token) => {
+        const makeFetchRequest = async (token) => {
             return requestWithRetry(`${apiUrl}/fetch-contacts`, {
                 method: "POST",
                 headers: {
@@ -214,7 +299,30 @@ function createSmartProspectProvider(config) {
         };
         try {
             const token = await getAuthToken();
-            return await makeRequest(token);
+            const fetchResult = await makeFetchRequest(token);
+            // If fetch-contacts returns pending status with filter_id, poll for results
+            const filterId = fetchResult.data?.filter_id;
+            const status = fetchResult.data?.status;
+            if (filterId && status === "pending") {
+                const pollResult = await pollForContactResults(filterId, contactIds.length);
+                if (pollResult.success && pollResult.data.list.length > 0) {
+                    return {
+                        success: true,
+                        message: "Fetch completed",
+                        data: {
+                            list: pollResult.data.list,
+                            total_count: pollResult.data.total_count,
+                            metrics: pollResult.data.metrics,
+                            leads_found: pollResult.data.metrics.totalContacts,
+                            email_fetched: pollResult.data.metrics.totalEmails,
+                            verification_status_list: [],
+                            filter_id: filterId,
+                            status: "completed",
+                        },
+                    };
+                }
+            }
+            return fetchResult;
         }
         catch (err) {
             // On 401, clear token and retry once with fresh token
@@ -224,7 +332,7 @@ function createSmartProspectProvider(config) {
                 await handleAuthError();
                 try {
                     const freshToken = await getAuthToken();
-                    return await makeRequest(freshToken);
+                    return await makeFetchRequest(freshToken);
                 }
                 catch {
                     // Retry failed too
@@ -252,6 +360,22 @@ function createSmartProspectProvider(config) {
             };
         }
     }
+    /**
+     * Calculate confidence score for a contact
+     */
+    function calculateConfidence(contact) {
+        const isVerified = contact.verificationStatus === "valid";
+        const isCatchAll = contact.verificationStatus === "catch_all";
+        const deliverability = contact.emailDeliverability || 0;
+        let confidence = deliverability * 100;
+        if (isVerified) {
+            confidence = Math.max(confidence, 90);
+        }
+        else if (isCatchAll) {
+            confidence = Math.min(confidence, 75);
+        }
+        return confidence;
+    }
     async function fetchEmail(candidate) {
         const { firstName, lastName } = extractNames(candidate);
         if (!firstName) {
@@ -270,64 +394,507 @@ function createSmartProspectProvider(config) {
             candidate.companyDomain ||
             candidate.company_domain ||
             undefined;
-        // Build search filters
+        // Build search filters using correct API field names
         const filters = {
             name: [fullName],
-            limit: 5, // Get top 5 to find best match
+            limit: 10, // Get more results to return multiple emails
         };
         if (company) {
-            filters.company = [company];
+            filters.companyName = [company];
         }
         if (domain) {
-            filters.domain = [domain];
+            filters.companyDomain = [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
+        // Score and sort all matches
         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) {
+        const scoredMatches = matches
+            .map((contact) => ({
+            contact,
+            score: calculateMatchScore(contact, fullName, company, title),
+        }))
+            .filter((m) => m.score > 0) // Only include matches with some relevance
+            .sort((a, b) => b.score - a.score);
+        if (scoredMatches.length === 0) {
             return null;
         }
-        // Step 2: Fetch email for best match (COSTS CREDITS)
-        const fetchResult = await fetchContacts([bestMatch.id]);
+        // Step 2: Fetch emails for ALL matching contacts (COSTS CREDITS)
+        // Note: This costs more credits but gives us all available emails
+        const contactIds = scoredMatches.map((m) => m.contact.id);
+        const fetchResult = await fetchContacts(contactIds);
         if (!fetchResult.success || fetchResult.data.list.length === 0) {
             return null;
         }
-        const enrichedContact = fetchResult.data.list[0];
-        const email = enrichedContact?.email;
-        if (!email) {
+        // Build multi-result with all found emails
+        const emails = [];
+        const seenEmails = new Set();
+        for (const enrichedContact of fetchResult.data.list) {
+            const email = enrichedContact?.email;
+            if (!email)
+                continue;
+            const emailLower = email.toLowerCase();
+            if (seenEmails.has(emailLower))
+                continue;
+            seenEmails.add(emailLower);
+            const isVerified = enrichedContact.verificationStatus === "valid";
+            const isCatchAll = enrichedContact.verificationStatus === "catch_all";
+            emails.push({
+                email,
+                verified: isVerified || isCatchAll,
+                confidence: calculateConfidence(enrichedContact),
+                isCatchAll,
+                metadata: {
+                    fullName: enrichedContact.fullName,
+                    title: enrichedContact.title,
+                    company: enrichedContact.company?.name,
+                    linkedin: enrichedContact.linkedin,
+                    verificationStatus: enrichedContact.verificationStatus,
+                    matchScore: scoredMatches.find((m) => m.contact.id === enrichedContact.id)?.score,
+                },
+            });
+        }
+        if (emails.length === 0) {
             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);
+        // Sort by confidence (highest first)
+        emails.sort((a, b) => (b.confidence ?? 0) - (a.confidence ?? 0));
+        // Return multi-result format
+        return { emails };
+    }
+    // Mark provider name for orchestrator
+    fetchEmail.__name = "smartprospect";
+    return fetchEmail;
+}
+/**
+ * Create a SmartProspect client for direct API access
+ *
+ * This provides access to the full SmartProspect API for:
+ * - Searching contacts with comprehensive filters (FREE)
+ * - Fetching/enriching contact emails (COSTS CREDITS)
+ * - Combined search + fetch operations
+ *
+ * @example
+ * ```ts
+ * const client = createSmartProspectClient({
+ *   email: 'user@example.com',
+ *   password: 'password123'
+ * });
+ *
+ * // Search only (FREE)
+ * const results = await client.search({
+ *   title: ['CEO', 'CTO'],
+ *   company: ['Google', 'Microsoft'],
+ *   level: ['C-Level'],
+ *   companyHeadCount: ['1001-5000', '5001-10000'],
+ *   limit: 25
+ * });
+ *
+ * // Fetch specific contacts (COSTS CREDITS)
+ * const enriched = await client.fetch(['contact-id-1', 'contact-id-2']);
+ * ```
+ */
+function createSmartProspectClient(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 null;
+    }
+    /**
+     * Get the current auth token
+     */
+    async function getAuthToken() {
+        if (hasDirectToken) {
+            return apiToken;
         }
-        else if (isCatchAll) {
-            confidence = Math.min(confidence, 75);
+        return (0, smartlead_auth_1.getSmartLeadToken)({
+            credentials: { email: email, password: password },
+            loginUrl,
+        });
+    }
+    /**
+     * Handle 401 errors
+     */
+    async function handleAuthError() {
+        if (hasCredentials) {
+            (0, smartlead_auth_1.clearSmartLeadToken)(email);
+        }
+    }
+    // Eager initialization
+    if (eagerInit && hasCredentials) {
+        getAuthToken().catch(() => { });
+    }
+    /**
+     * Build the request payload with proper defaults
+     * Field names match the actual SmartProspect API
+     */
+    function buildSearchPayload(filters) {
+        const payload = {};
+        // Contact-based filters
+        if (filters.name?.length)
+            payload.name = filters.name;
+        if (filters.firstName?.length)
+            payload.firstName = filters.firstName;
+        if (filters.lastName?.length)
+            payload.lastName = filters.lastName;
+        // Title filters
+        if (filters.title?.length)
+            payload.title = filters.title;
+        payload.titleExactMatch = filters.titleExactMatch ?? false;
+        // Department & Level
+        if (filters.department?.length)
+            payload.department = filters.department;
+        if (filters.level?.length)
+            payload.level = filters.level;
+        // Company filters (note: API uses companyName and companyDomain)
+        if (filters.companyName?.length)
+            payload.companyName = filters.companyName;
+        if (filters.companyDomain?.length)
+            payload.companyDomain = filters.companyDomain;
+        // Industry filters (note: API uses companyIndustry and companySubIndustry)
+        if (filters.companyIndustry?.length)
+            payload.companyIndustry = filters.companyIndustry;
+        if (filters.companySubIndustry?.length)
+            payload.companySubIndustry = filters.companySubIndustry;
+        // Company size filters
+        if (filters.companyHeadCount?.length)
+            payload.companyHeadCount = filters.companyHeadCount;
+        if (filters.companyRevenue?.length)
+            payload.companyRevenue = filters.companyRevenue;
+        // Location filters
+        if (filters.country?.length)
+            payload.country = filters.country;
+        if (filters.state?.length)
+            payload.state = filters.state;
+        if (filters.city?.length)
+            payload.city = filters.city;
+        // Workflow options
+        payload.dontDisplayOwnedContact = filters.dontDisplayOwnedContact ?? true;
+        // Pagination
+        payload.limit = filters.limit ?? 25;
+        if (filters.scroll_id)
+            payload.scroll_id = filters.scroll_id;
+        return payload;
+    }
+    /**
+     * Search for contacts (FREE - no credits)
+     */
+    async function search(filters) {
+        const payload = buildSearchPayload(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(payload),
+            });
+        };
+        try {
+            const token = await getAuthToken();
+            return await makeRequest(token);
+        }
+        catch (err) {
+            if (err instanceof Error &&
+                err.message.includes("401") &&
+                hasCredentials) {
+                await handleAuthError();
+                try {
+                    const freshToken = await getAuthToken();
+                    return await makeRequest(freshToken);
+                }
+                catch {
+                    // Retry failed
+                }
+            }
+            return {
+                success: false,
+                message: err instanceof Error ? err.message : "Search failed",
+                data: { list: [], total_count: 0 },
+            };
+        }
+    }
+    /**
+     * Poll get-contacts until email lookup is complete
+     */
+    async function pollForResults(filterId, expectedCount, pollingConfig = DEFAULT_POLLING_CONFIG) {
+        const { initialDelay, pollInterval, maxAttempts, maxWaitTime } = pollingConfig;
+        const startTime = Date.now();
+        // Wait initial delay before first poll
+        await delay(initialDelay);
+        const makeRequest = async (token) => {
+            return requestWithRetry(`${apiUrl}/get-contacts`, {
+                method: "POST",
+                headers: {
+                    Authorization: `Bearer ${token}`,
+                    "Content-Type": "application/json",
+                    Accept: "application/json",
+                },
+                body: JSON.stringify({
+                    filter_id: filterId,
+                    limit: expectedCount,
+                    offset: 0,
+                }),
+            });
+        };
+        for (let attempt = 0; attempt < maxAttempts; attempt++) {
+            // Check if we've exceeded max wait time
+            if (Date.now() - startTime > maxWaitTime) {
+                break;
+            }
+            try {
+                const token = await getAuthToken();
+                const result = await makeRequest(token);
+                if (result.success && result.data.metrics) {
+                    const { completed, totalContacts } = result.data.metrics;
+                    // Check if all contacts have been processed
+                    if (completed >= totalContacts || completed >= expectedCount) {
+                        return result;
+                    }
+                }
+                // Wait before next poll
+                await delay(pollInterval);
+            }
+            catch (err) {
+                // On 401, clear token and retry
+                if (err instanceof Error &&
+                    err.message.includes("401") &&
+                    hasCredentials) {
+                    await handleAuthError();
+                }
+                // Continue polling on errors
+                await delay(pollInterval);
+            }
+        }
+        // Return last result even if not complete
+        try {
+            const token = await getAuthToken();
+            return await makeRequest(token);
+        }
+        catch {
+            return {
+                success: false,
+                message: "Polling timed out",
+                data: {
+                    list: [],
+                    total_count: 0,
+                    metrics: {
+                        totalContacts: 0,
+                        totalEmails: 0,
+                        noEmailFound: 0,
+                        invalidEmails: 0,
+                        catchAllEmails: 0,
+                        verifiedEmails: 0,
+                        completed: 0,
+                    },
+                },
+            };
         }
+    }
+    /**
+     * Fetch/enrich emails for specific contact IDs (COSTS CREDITS)
+     *
+     * SmartProspect uses async email lookup:
+     * 1. Call fetch-contacts to initiate lookup (returns immediately with status: "pending")
+     * 2. Poll get-contacts until metrics.completed >= expected count
+     * 3. Return the final enriched contacts with emails
+     */
+    async function fetch(contactIds) {
+        if (!contactIds.length) {
+            return {
+                success: true,
+                message: "No contacts to fetch",
+                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: [],
+                },
+            };
+        }
+        const makeFetchRequest = 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();
+            const fetchResult = await makeFetchRequest(token);
+            // If fetch-contacts returns a filter_id with pending status, we need to poll
+            const filterId = fetchResult.data?.filter_id;
+            const status = fetchResult.data?.status;
+            if (filterId && status === "pending") {
+                // Poll get-contacts for final results
+                const pollResult = await pollForResults(filterId, contactIds.length);
+                if (pollResult.success && pollResult.data.list.length > 0) {
+                    // Convert poll result to fetch response format
+                    return {
+                        success: true,
+                        message: "Fetch completed",
+                        data: {
+                            list: pollResult.data.list,
+                            total_count: pollResult.data.total_count,
+                            metrics: pollResult.data.metrics,
+                            leads_found: pollResult.data.metrics.totalContacts,
+                            email_fetched: pollResult.data.metrics.totalEmails,
+                            verification_status_list: [],
+                            filter_id: filterId,
+                            status: "completed",
+                        },
+                    };
+                }
+            }
+            // If no polling needed or polling failed, return original result
+            return fetchResult;
+        }
+        catch (err) {
+            if (err instanceof Error &&
+                err.message.includes("401") &&
+                hasCredentials) {
+                await handleAuthError();
+                try {
+                    const freshToken = await getAuthToken();
+                    return await makeFetchRequest(freshToken);
+                }
+                catch {
+                    // Retry failed
+                }
+            }
+            return {
+                success: false,
+                message: err instanceof Error ? err.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: [],
+                },
+            };
+        }
+    }
+    /**
+     * Search and immediately fetch all results
+     */
+    async function searchAndFetch(filters) {
+        const searchResponse = await search(filters);
+        if (!searchResponse.success || searchResponse.data.list.length === 0) {
+            return {
+                searchResponse,
+                fetchResponse: null,
+                contacts: [],
+            };
+        }
+        const contactIds = searchResponse.data.list.map((c) => c.id);
+        const fetchResponse = await fetch(contactIds);
         return {
-            email,
-            verified: isVerified || isCatchAll, // Accept catch-all as semi-verified
-            score: confidence,
+            searchResponse,
+            fetchResponse,
+            contacts: fetchResponse.success ? fetchResponse.data.list : [],
         };
     }
-    // Mark provider name for orchestrator
-    fetchEmail.__name = "smartprospect";
-    return fetchEmail;
+    /**
+     * Generic location lookup (countries, states, cities)
+     */
+    async function getLocations(type, options = {}) {
+        const { search: searchQuery, limit = 20, offset = 0 } = options;
+        const params = new URLSearchParams();
+        params.set('limit', String(limit));
+        if (offset > 0)
+            params.set('offset', String(offset));
+        if (searchQuery)
+            params.set('search', searchQuery);
+        const makeRequest = async (token) => {
+            return requestWithRetry(`${apiUrl}/${type}?${params.toString()}`, {
+                method: "GET",
+                headers: {
+                    Authorization: `Bearer ${token}`,
+                    Accept: "application/json",
+                },
+            });
+        };
+        try {
+            const token = await getAuthToken();
+            return await makeRequest(token);
+        }
+        catch (err) {
+            if (err instanceof Error &&
+                err.message.includes("401") &&
+                hasCredentials) {
+                await handleAuthError();
+                try {
+                    const freshToken = await getAuthToken();
+                    return await makeRequest(freshToken);
+                }
+                catch {
+                    // Retry failed
+                }
+            }
+            return {
+                success: false,
+                message: err instanceof Error ? err.message : "Lookup failed",
+                data: [],
+                pagination: { limit, offset, page: 1, count: 0 },
+                search: searchQuery || null,
+            };
+        }
+    }
+    /**
+     * Lookup countries (for typeahead)
+     */
+    async function getCountries(options) {
+        return getLocations('countries', options);
+    }
+    /**
+     * Lookup states (for typeahead)
+     */
+    async function getStates(options) {
+        return getLocations('states', options);
+    }
+    /**
+     * Lookup cities (for typeahead)
+     */
+    async function getCities(options) {
+        return getLocations('cities', options);
+    }
+    return {
+        search,
+        fetch,
+        searchAndFetch,
+        getCountries,
+        getStates,
+        getCities,
+    };
 }