linkedin-secret-sauce 0.5.1 → 0.6.0

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";
 /**
@@ -252,6 +257,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 +291,399 @@ 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 },
+            };
+        }
+    }
+    /**
+     * 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,
+    };
 }

package/dist/enrichment/types.d.ts

@@ -30,10 +30,62 @@ export interface ProviderResult {
     score?: number;
     confidence?: number;
 }
+/**
+ * Extended provider result that can return multiple emails
+ */
+export interface ProviderMultiResult {
+    emails: Array<{
+        email: string;
+        verified?: boolean;
+        confidence?: number;
+        isCatchAll?: boolean;
+        metadata?: Record<string, unknown>;
+    }>;
+}
+/**
+ * Email type classification
+ */
+export type EmailType = 'business' | 'personal' | 'disposable' | 'role' | 'unknown';
+/**
+ * Individual enriched email with full metadata
+ */
+export interface EnrichedEmail {
+    /** The email address */
+    email: string;
+    /** Which provider found this email */
+    source: ProviderName;
+    /** Confidence score (0-100) */
+    confidence: number;
+    /** Whether the email was verified */
+    verified: boolean;
+    /** Email type classification */
+    type: EmailType;
+    /** Whether this is a catch-all domain */
+    isCatchAll?: boolean;
+    /** ISO timestamp of when this was found */
+    foundAt: string;
+    /** Additional provider-specific metadata */
+    metadata?: Record<string, unknown>;
+}
+/**
+ * Result containing all found emails from all providers
+ */
+export interface MultiEmailResult {
+    /** All found emails, sorted by confidence (highest first) */
+    emails: EnrichedEmail[];
+    /** The original candidate */
+    candidate: EnrichmentCandidate;
+    /** Total cost incurred across all providers */
+    totalCost: number;
+    /** List of providers that were queried */
+    providersQueried: ProviderName[];
+    /** ISO timestamp of when enrichment completed */
+    completedAt: string;
+}
 /**
  * Provider function signature
  */
-export type ProviderFunc = (candidate: EnrichmentCandidate) => Promise<ProviderResult | null>;
+export type ProviderFunc = (candidate: EnrichmentCandidate) => Promise<ProviderResult | ProviderMultiResult | null>;
 /**
  * Input candidate for enrichment - flexible to accept various naming conventions
  */
@@ -193,12 +245,16 @@ export interface EnrichmentClientConfig {
  * Enrichment client interface
  */
 export interface EnrichmentClient {
-    /** Enrich a single candidate */
+    /** Enrich a single candidate - returns first valid business email (original behavior) */
     enrich: (candidate: EnrichmentCandidate) => Promise<CanonicalEmail>;
-    /** Enrich multiple candidates in batches */
+    /** Enrich multiple candidates in batches - returns first valid business email per candidate */
     enrichBatch: (candidates: EnrichmentCandidate[], options?: BatchEnrichmentOptions) => Promise<Array<{
         candidate: EnrichmentCandidate;
     } & CanonicalEmail>>;
+    /** Enrich a single candidate - returns ALL found emails from ALL providers */
+    enrichAll: (candidate: EnrichmentCandidate) => Promise<MultiEmailResult>;
+    /** Enrich multiple candidates - returns ALL found emails for each candidate */
+    enrichAllBatch: (candidates: EnrichmentCandidate[], options?: BatchEnrichmentOptions) => Promise<MultiEmailResult[]>;
 }
 /**
  * Available provider names
@@ -260,26 +316,77 @@ export interface SmartProspectContact {
     verificationStatus?: string;
     catchAllStatus?: string;
 }
+/**
+ * SmartProspect Search Filters
+ *
+ * Comprehensive filter interface matching SmartProspect/Smartlead's actual API.
+ * Field names and values match their exact API structure.
+ */
 export interface SmartProspectSearchFilters {
+    /** Full name (searches across first + last) */
     name?: string[];
+    /** First name only */
     firstName?: string[];
+    /** Last name only */
     lastName?: string[];
+    /** Job titles to search (free text, e.g., "CEO", "Software Engineer") */
     title?: string[];
-    company?: string[];
-    domain?: string[];
-    department?: string[];
-    level?: string[];
-    industry?: string[];
+    /** Whether to match titles exactly (default: false) */
+    titleExactMatch?: boolean;
+    /** Departments - must use exact API values */
+    department?: SmartProspectDepartment[];
+    /** Seniority levels - must use exact API values */
+    level?: SmartProspectLevel[];
+    /** Company names (e.g., "Google", "Microsoft") */
+    companyName?: string[];
+    /** Company domains (e.g., "google.com", "microsoft.com") */
+    companyDomain?: string[];
+    /** Industries - must use exact API values */
+    companyIndustry?: SmartProspectIndustry[];
+    /** Sub-industries - must use exact API values */
+    companySubIndustry?: string[];
+    /** Headcount ranges - must use exact API values */
+    companyHeadCount?: SmartProspectHeadcount[];
+    /** Revenue ranges - must use exact API values */
+    companyRevenue?: SmartProspectRevenue[];
+    /** Countries (e.g., "United States", "United Kingdom", "Germany") */
     country?: string[];
+    /** States with country (e.g., "California, United States", "Bavaria, Germany") */
     state?: string[];
+    /** Cities with state and country (e.g., "San Francisco, California, United States") */
     city?: string[];
-    companyHeadCount?: string[];
-    companyRevenue?: string[];
+    /** Don't include contacts already owned/in campaigns (default: true) */
     dontDisplayOwnedContact?: boolean;
+    /** Number of results to return (default: 25, max: 100) */
     limit?: number;
-    titleExactMatch?: boolean;
+    /** Scroll ID for cursor-based pagination (from previous response) */
     scroll_id?: string;
 }
+/**
+ * SmartProspect Department values (exact API values)
+ */
+export type SmartProspectDepartment = 'Engineering' | 'Finance & Administration' | 'Human Resources' | 'IT & IS' | 'Marketing' | 'Operations' | 'Other' | 'Support' | 'Sales';
+/**
+ * SmartProspect Level/Seniority values (exact API values)
+ */
+export type SmartProspectLevel = 'Staff' | 'Manager-Level' | 'Director-Level' | 'VP-Level' | 'C-Level';
+/**
+ * SmartProspect Headcount ranges (exact API values)
+ */
+export type SmartProspectHeadcount = '0 - 25' | '25 - 100' | '100 - 250' | '250 - 1000' | '1K - 10K' | '10K - 50K' | '50K - 100K' | '> 100K';
+/**
+ * SmartProspect Revenue ranges (exact API values)
+ */
+export type SmartProspectRevenue = '$0 - 1M' | '$1 - 10M' | '$10 - 50M' | '$50 - 100M' | '$100 - 250M' | '$250 - 500M' | '$500M - 1B' | '> $1B';
+/**
+ * SmartProspect Industry values (exact API values)
+ */
+export type SmartProspectIndustry = 'Software & Internet' | 'Business Services' | 'Real Estate & Construction' | 'Financial Services' | 'Healthcare, Pharmaceuticals, & Biotech' | 'Retail' | 'Consumer Services' | 'Education' | 'Media & Entertainment' | 'Travel, Recreation, and Leisure' | 'Transportation & Storage' | 'Manufacturing' | 'Wholesale & Distribution' | 'Non-Profit' | 'Energy & Utilities' | 'Government' | 'Agriculture & Mining' | 'Computers & Electronics' | 'Telecommunications' | 'Other';
+/**
+ * SmartProspect Sub-Industry values (exact API values - partial list)
+ * Note: This is a subset of available sub-industries. The API accepts many more.
+ */
+export declare const SMARTPROSPECT_SUB_INDUSTRIES: readonly ["Internet", "Information Technology and Services", "Information Services", "Computer Software", "Computer & Network Security", "Computer Games", "Glass, Ceramics & Concrete", "Construction", "Commercial Real Estate", "Civil Engineering", "Building Materials", "Architecture & Planning", "Writing and Editing", "Translation and Localization", "Think Tanks", "Staffing and Recruiting", "Security and Investigations", "Public Safety", "Public Relations and Communications", "Program Development", "Professional Training & Coaching", "Market Research", "Marketing and Advertising", "Management Consulting", "Legal Services", "Law Practice", "Law Enforcement", "International Trade and Development", "Import and Export", "Human Resources", "Graphic Design", "Facilities Services", "Executive Office", "Events Services", "Environmental Services", "Design", "Business Supplies and Equipment", "Animation", "Alternative Dispute Resolution", "Outsourcing/Offshoring"];
 export interface SmartProspectSearchResponse {
     success: boolean;
     message: string;
@@ -290,6 +397,27 @@ export interface SmartProspectSearchResponse {
         total_count: number;
     };
 }
+/**
+ * SmartProspect Location lookup response (countries, states, cities)
+ */
+export interface SmartProspectLocationItem {
+    id: number;
+    country_name?: string;
+    state_name?: string;
+    city_name?: string;
+}
+export interface SmartProspectLocationResponse {
+    success: boolean;
+    message: string;
+    data: SmartProspectLocationItem[];
+    pagination: {
+        limit: number;
+        offset: number;
+        page: number;
+        count: number;
+    };
+    search: string | null;
+}
 export interface SmartProspectFetchResponse {
     success: boolean;
     message: string;