linkedin-secret-sauce 0.5.0 → 0.6.0

package/dist/enrichment/providers/smartprospect.js

@@ -4,10 +4,20 @@
  *
  * 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
+ *
+ * Exports:
+ * - createSmartProspectProvider: For email enrichment (waterfall pattern)
+ * - createSmartProspectClient: Full client with search/fetch capabilities
  */
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.createSmartProspectProvider = createSmartProspectProvider;
-const DEFAULT_API_URL = 'https://prospect-api.smartlead.ai/api/search-email-leads';
+exports.createSmartProspectClient = createSmartProspectClient;
+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
  */
@@ -28,7 +38,7 @@ async function requestWithRetry(url, options, retries = 2, backoffMs = 300) {
                 continue;
             }
             if (!res.ok) {
-                const errorText = await res.text().catch(() => '');
+                const errorText = await res.text().catch(() => "");
                 throw new Error(`SmartProspect API error: ${res.status} - ${errorText}`);
             }
             return (await res.json());
@@ -41,7 +51,7 @@ async function requestWithRetry(url, options, retries = 2, backoffMs = 300) {
             }
         }
     }
-    throw lastErr ?? new Error('smartprospect_http_error');
+    throw lastErr ?? new Error("smartprospect_http_error");
 }
 /**
  * Calculate match score between search input and contact result
@@ -49,30 +59,33 @@ async function requestWithRetry(url, options, retries = 2, backoffMs = 300) {
 function calculateMatchScore(contact, searchName, company, title) {
     let score = 0;
     // Name match scoring (0-50 points)
-    const contactName = contact.fullName?.toLowerCase() || '';
+    const contactName = contact.fullName?.toLowerCase() || "";
     const searchNameLower = searchName.toLowerCase();
     if (contactName === searchNameLower) {
         score += 50; // Exact match
     }
-    else if (contactName.includes(searchNameLower) || searchNameLower.includes(contactName)) {
+    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 contactCompany = contact.company?.name?.toLowerCase() || "";
         const searchCompany = company.toLowerCase();
         if (contactCompany === searchCompany) {
             score += 30; // Exact match
         }
-        else if (contactCompany.includes(searchCompany) || searchCompany.includes(contactCompany)) {
+        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 contactTitle = contact.title?.toLowerCase() || "";
         const searchTitle = title.toLowerCase();
-        if (contactTitle.includes(searchTitle) || searchTitle.includes(contactTitle)) {
+        if (contactTitle.includes(searchTitle) ||
+            searchTitle.includes(contactTitle)) {
             score += 10;
         }
     }
@@ -89,37 +102,72 @@ function extractNames(candidate) {
     const firstName = candidate.firstName ||
         candidate.first_name ||
         candidate.first ||
-        candidate.name?.split(' ')?.[0] ||
-        '';
+        candidate.name?.split(" ")?.[0] ||
+        "";
     const lastName = candidate.lastName ||
         candidate.last_name ||
         candidate.last ||
-        candidate.name?.split(' ')?.slice(1).join(' ') ||
-        '';
+        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, apiUrl = DEFAULT_API_URL } = config;
-    if (!apiToken) {
+    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';
+        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) {
-        try {
-            const response = await requestWithRetry(`${apiUrl}/search-contacts`, {
-                method: 'POST',
+        const makeRequest = async (token) => {
+            return requestWithRetry(`${apiUrl}/search-contacts`, {
+                method: "POST",
                 headers: {
-                    Authorization: `Bearer ${apiToken}`,
-                    'Content-Type': 'application/json',
-                    Accept: 'application/json',
+                    Authorization: `Bearer ${token}`,
+                    "Content-Type": "application/json",
+                    Accept: "application/json",
                 },
                 body: JSON.stringify({
                     ...filters,
@@ -128,12 +176,28 @@ function createSmartProspectProvider(config) {
                     titleExactMatch: filters.titleExactMatch ?? false,
                 }),
             });
-            return response;
+        };
+        try {
+            const token = await getAuthToken();
+            return await makeRequest(token);
         }
-        catch {
+        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',
+                message: "Search failed",
                 data: { list: [], total_count: 0 },
             };
         }
@@ -142,22 +206,38 @@ function createSmartProspectProvider(config) {
      * Fetch/enrich emails for specific contact IDs (COSTS CREDITS)
      */
     async function fetchContacts(contactIds) {
-        try {
-            const response = await requestWithRetry(`${apiUrl}/fetch-contacts`, {
-                method: 'POST',
+        const makeRequest = async (token) => {
+            return requestWithRetry(`${apiUrl}/fetch-contacts`, {
+                method: "POST",
                 headers: {
-                    Authorization: `Bearer ${apiToken}`,
-                    'Content-Type': 'application/json',
-                    Accept: 'application/json',
+                    Authorization: `Bearer ${token}`,
+                    "Content-Type": "application/json",
+                    Accept: "application/json",
                 },
                 body: JSON.stringify({ contactIds }),
             });
-            return response;
+        };
+        try {
+            const token = await getAuthToken();
+            return await makeRequest(token);
         }
-        catch {
+        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',
+                message: "Fetch failed",
                 data: {
                     list: [],
                     total_count: 0,
@@ -177,73 +257,433 @@ 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) {
             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 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 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 },
+            };
+        }
+    }
+    /**
+     * Fetch/enrich emails for specific contact IDs (COSTS CREDITS)
+     */
+    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 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) {
+            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 : "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,
+    };
 }