linkedin-secret-sauce 0.5.0 → 0.6.0

package/dist/enrichment/matching.js

@@ -0,0 +1,619 @@
+"use strict";
+/**
+ * Contact Matching Utilities
+ *
+ * Matches contacts between LinkedIn Sales Navigator and SmartProspect
+ * to find the same person across both platforms.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.calculateMatchConfidence = calculateMatchConfidence;
+exports.classifyMatchQuality = classifyMatchQuality;
+exports.findBestMatch = findBestMatch;
+exports.matchContacts = matchContacts;
+exports.buildSmartProspectFiltersFromLinkedIn = buildSmartProspectFiltersFromLinkedIn;
+exports.parseLinkedInSearchResponse = parseLinkedInSearchResponse;
+exports.enrichLinkedInContact = enrichLinkedInContact;
+exports.enrichLinkedInContactsBatch = enrichLinkedInContactsBatch;
+exports.createLinkedInEnricher = createLinkedInEnricher;
+const smartprospect_1 = require("./providers/smartprospect");
+// =============================================================================
+// Utility Functions
+// =============================================================================
+/**
+ * Normalize a string for comparison (lowercase, trim, remove extra spaces)
+ */
+function normalize(str) {
+    if (!str)
+        return '';
+    return str.toLowerCase().trim().replace(/\s+/g, ' ');
+}
+/**
+ * Extract company name from LinkedIn position
+ */
+function getLinkedInCompany(contact) {
+    const pos = contact.currentPositions?.[0];
+    if (!pos)
+        return '';
+    return pos.companyUrnResolutionResult?.name || pos.companyName || '';
+}
+/**
+ * Extract job title from LinkedIn position
+ */
+function getLinkedInTitle(contact) {
+    const pos = contact.currentPositions?.[0];
+    return pos?.title || '';
+}
+/**
+ * Extract location parts from LinkedIn geoRegion
+ * Format: "City, State, Country" or "City, Country" or just "Country"
+ */
+function parseLinkedInLocation(geoRegion) {
+    if (!geoRegion)
+        return { city: '', state: '', country: '' };
+    const parts = geoRegion.split(',').map((p) => p.trim());
+    if (parts.length >= 3) {
+        return {
+            city: parts[0],
+            state: parts[1],
+            country: parts[parts.length - 1],
+        };
+    }
+    else if (parts.length === 2) {
+        return {
+            city: parts[0],
+            state: '',
+            country: parts[1],
+        };
+    }
+    else {
+        return {
+            city: '',
+            state: '',
+            country: parts[0] || '',
+        };
+    }
+}
+/**
+ * Calculate Levenshtein distance between two strings
+ */
+function levenshteinDistance(a, b) {
+    const matrix = [];
+    for (let i = 0; i <= b.length; i++) {
+        matrix[i] = [i];
+    }
+    for (let j = 0; j <= a.length; j++) {
+        matrix[0][j] = j;
+    }
+    for (let i = 1; i <= b.length; i++) {
+        for (let j = 1; j <= a.length; j++) {
+            if (b.charAt(i - 1) === a.charAt(j - 1)) {
+                matrix[i][j] = matrix[i - 1][j - 1];
+            }
+            else {
+                matrix[i][j] = Math.min(matrix[i - 1][j - 1] + 1, matrix[i][j - 1] + 1, matrix[i - 1][j] + 1);
+            }
+        }
+    }
+    return matrix[b.length][a.length];
+}
+/**
+ * Calculate string similarity (0-1) using Levenshtein distance
+ */
+function stringSimilarity(a, b) {
+    const na = normalize(a);
+    const nb = normalize(b);
+    if (na === nb)
+        return 1;
+    if (!na || !nb)
+        return 0;
+    const maxLen = Math.max(na.length, nb.length);
+    const distance = levenshteinDistance(na, nb);
+    return 1 - distance / maxLen;
+}
+/**
+ * Check if strings match exactly (normalized)
+ */
+function exactMatch(a, b) {
+    return normalize(a) === normalize(b) && normalize(a) !== '';
+}
+/**
+ * Check if strings match with fuzzy tolerance
+ */
+function fuzzyMatch(a, b, threshold = 0.85) {
+    return stringSimilarity(a, b) >= threshold;
+}
+/**
+ * Check if one string contains the other
+ */
+function containsMatch(a, b) {
+    const na = normalize(a);
+    const nb = normalize(b);
+    if (!na || !nb)
+        return false;
+    return na.includes(nb) || nb.includes(na);
+}
+// =============================================================================
+// Main Matching Functions
+// =============================================================================
+/**
+ * Calculate match confidence between a LinkedIn contact and SmartProspect contact
+ */
+function calculateMatchConfidence(linkedin, smartprospect, options = {}) {
+    const { fuzzyNames = true, fuzzyCompany = true } = options;
+    const matchedFields = [];
+    let score = 0;
+    // === Name matching (up to 40 points) ===
+    const liFirstName = normalize(linkedin.firstName);
+    const liLastName = normalize(linkedin.lastName);
+    const spFirstName = normalize(smartprospect.firstName);
+    const spLastName = normalize(smartprospect.lastName);
+    // First name match
+    if (exactMatch(linkedin.firstName, smartprospect.firstName)) {
+        score += 20;
+        matchedFields.push('firstName:exact');
+    }
+    else if (fuzzyNames && fuzzyMatch(linkedin.firstName, smartprospect.firstName)) {
+        score += 15;
+        matchedFields.push('firstName:fuzzy');
+    }
+    // Last name match
+    if (exactMatch(linkedin.lastName, smartprospect.lastName)) {
+        score += 20;
+        matchedFields.push('lastName:exact');
+    }
+    else if (fuzzyNames && fuzzyMatch(linkedin.lastName, smartprospect.lastName)) {
+        score += 15;
+        matchedFields.push('lastName:fuzzy');
+    }
+    // === Company matching (up to 30 points) ===
+    const liCompany = getLinkedInCompany(linkedin);
+    const spCompany = smartprospect.company?.name || '';
+    if (exactMatch(liCompany, spCompany)) {
+        score += 30;
+        matchedFields.push('company:exact');
+    }
+    else if (fuzzyCompany && fuzzyMatch(liCompany, spCompany, 0.8)) {
+        score += 25;
+        matchedFields.push('company:fuzzy');
+    }
+    else if (containsMatch(liCompany, spCompany)) {
+        score += 15;
+        matchedFields.push('company:contains');
+    }
+    // === Title matching (up to 15 points) ===
+    const liTitle = getLinkedInTitle(linkedin);
+    const spTitle = smartprospect.title || '';
+    if (exactMatch(liTitle, spTitle)) {
+        score += 15;
+        matchedFields.push('title:exact');
+    }
+    else if (fuzzyMatch(liTitle, spTitle, 0.75)) {
+        score += 12;
+        matchedFields.push('title:fuzzy');
+    }
+    else if (containsMatch(liTitle, spTitle)) {
+        score += 8;
+        matchedFields.push('title:contains');
+    }
+    // === Location matching (up to 15 points) ===
+    const liLocation = parseLinkedInLocation(linkedin.geoRegion);
+    const spCountry = normalize(smartprospect.country);
+    const spState = normalize(smartprospect.state);
+    const spCity = normalize(smartprospect.city);
+    // Country match
+    if (spCountry && exactMatch(liLocation.country, smartprospect.country)) {
+        score += 5;
+        matchedFields.push('country:exact');
+    }
+    // State match
+    if (spState && exactMatch(liLocation.state, smartprospect.state)) {
+        score += 5;
+        matchedFields.push('state:exact');
+    }
+    // City match
+    if (spCity && exactMatch(liLocation.city, smartprospect.city)) {
+        score += 5;
+        matchedFields.push('city:exact');
+    }
+    return { confidence: Math.min(100, score), matchedFields };
+}
+/**
+ * Classify match quality based on confidence and matched fields
+ */
+function classifyMatchQuality(confidence, matchedFields) {
+    const hasNameMatch = matchedFields.some((f) => f.startsWith('firstName:exact')) &&
+        matchedFields.some((f) => f.startsWith('lastName:exact'));
+    const hasCompanyMatch = matchedFields.some((f) => f.startsWith('company:'));
+    if (confidence >= 85 && hasNameMatch && hasCompanyMatch) {
+        return 'exact';
+    }
+    else if (confidence >= 70 && hasNameMatch) {
+        return 'high';
+    }
+    else if (confidence >= 50) {
+        return 'medium';
+    }
+    else if (confidence >= 30) {
+        return 'low';
+    }
+    return 'none';
+}
+/**
+ * Find the best matching SmartProspect contact for a LinkedIn contact
+ */
+function findBestMatch(linkedInContact, smartProspectContacts, options = {}) {
+    const { minConfidence = 50 } = options;
+    let bestMatch = null;
+    for (const spContact of smartProspectContacts) {
+        const { confidence, matchedFields } = calculateMatchConfidence(linkedInContact, spContact, options);
+        if (confidence >= minConfidence) {
+            if (!bestMatch || confidence > bestMatch.confidence) {
+                bestMatch = {
+                    smartProspectContact: spContact,
+                    linkedInContact,
+                    confidence,
+                    matchedFields,
+                    quality: classifyMatchQuality(confidence, matchedFields),
+                };
+            }
+        }
+    }
+    return bestMatch;
+}
+/**
+ * Match multiple LinkedIn contacts to SmartProspect contacts
+ */
+function matchContacts(linkedInContacts, smartProspectContacts, options = {}) {
+    const results = [];
+    for (const liContact of linkedInContacts) {
+        const match = findBestMatch(liContact, smartProspectContacts, options);
+        if (match) {
+            results.push(match);
+        }
+    }
+    // Sort by confidence descending
+    return results.sort((a, b) => b.confidence - a.confidence);
+}
+/**
+ * Build SmartProspect search filters from a LinkedIn contact
+ * This helps you search SmartProspect for a specific LinkedIn contact
+ */
+function buildSmartProspectFiltersFromLinkedIn(linkedInContact) {
+    const filters = {
+        firstName: [linkedInContact.firstName],
+        lastName: [linkedInContact.lastName],
+    };
+    const company = getLinkedInCompany(linkedInContact);
+    if (company) {
+        filters.companyName = [company];
+    }
+    const title = getLinkedInTitle(linkedInContact);
+    if (title) {
+        filters.title = [title];
+    }
+    const location = parseLinkedInLocation(linkedInContact.geoRegion);
+    if (location.country) {
+        filters.country = [location.country];
+    }
+    return filters;
+}
+/**
+ * Parse LinkedIn Sales Navigator API response elements into LinkedInContact array
+ */
+function parseLinkedInSearchResponse(elements) {
+    return elements.map((el) => ({
+        objectUrn: el.objectUrn,
+        entityUrn: el.entityUrn,
+        firstName: el.firstName || '',
+        lastName: el.lastName || '',
+        fullName: el.fullName || undefined,
+        geoRegion: el.geoRegion || undefined,
+        currentPositions: el.currentPositions,
+        profilePictureDisplayImage: el.profilePictureDisplayImage,
+    }));
+}
+// =============================================================================
+// High-Level Enrichment Function
+// =============================================================================
+/**
+ * Enrich a LinkedIn Sales Navigator contact using SmartProspect
+ *
+ * This is the main function consumers should use. It:
+ * 1. Takes a LinkedIn contact from Sales Navigator search results
+ * 2. Searches SmartProspect for matching candidates
+ * 3. Uses intelligent matching to find the exact same person
+ * 4. Optionally fetches their verified email (costs credits)
+ *
+ * @example
+ * ```ts
+ * import { enrichLinkedInContact } from 'linkedin-secret-sauce';
+ *
+ * // From your LinkedIn Sales Nav search result
+ * const linkedInContact = {
+ *   firstName: 'Valentin',
+ *   lastName: 'Rangelov',
+ *   geoRegion: 'Sofia, Sofia City, Bulgaria',
+ *   currentPositions: [{
+ *     companyName: 'Recruitica',
+ *     title: 'Chief Technology Officer'
+ *   }]
+ * };
+ *
+ * const result = await enrichLinkedInContact(linkedInContact, {
+ *   email: process.env.SMARTLEAD_EMAIL,
+ *   password: process.env.SMARTLEAD_PASSWORD
+ * });
+ *
+ * if (result.success && result.email) {
+ *   console.log(`Found email: ${result.email}`);
+ *   console.log(`Match confidence: ${result.matchConfidence}%`);
+ *   console.log(`Deliverability: ${result.emailDeliverability * 100}%`);
+ * }
+ * ```
+ */
+async function enrichLinkedInContact(linkedInContact, smartProspectConfig, options = {}) {
+    const { minConfidence = 60, autoFetch = true, fuzzyNames = true, fuzzyCompany = true, searchLimit = 25, includeCompany = true, includeLocation = false, } = options;
+    // Initialize result
+    const result = {
+        success: false,
+        linkedInContact,
+        matchedContact: null,
+        matchConfidence: 0,
+        matchQuality: 'none',
+        matchedFields: [],
+        email: null,
+        emailDeliverability: 0,
+        verificationStatus: null,
+        allCandidates: [],
+        totalCandidatesFound: 0,
+    };
+    // Create SmartProspect client
+    const client = (0, smartprospect_1.createSmartProspectClient)(smartProspectConfig);
+    if (!client) {
+        result.error = 'Failed to create SmartProspect client - check credentials';
+        return result;
+    }
+    try {
+        // Build search filters from LinkedIn contact
+        const filters = buildSmartProspectFiltersFromLinkedIn(linkedInContact);
+        // Optionally remove company filter for broader search
+        const searchFilters = {
+            firstName: filters.firstName,
+            lastName: filters.lastName,
+            limit: searchLimit,
+        };
+        if (includeCompany && filters.companyName) {
+            searchFilters.companyName = filters.companyName;
+        }
+        if (includeLocation && filters.country) {
+            searchFilters.country = filters.country;
+        }
+        // Step 1: Search SmartProspect (FREE)
+        const searchResponse = await client.search(searchFilters);
+        if (!searchResponse.success) {
+            result.error = `SmartProspect search failed: ${searchResponse.message}`;
+            return result;
+        }
+        result.allCandidates = searchResponse.data.list;
+        result.totalCandidatesFound = searchResponse.data.total_count;
+        if (searchResponse.data.list.length === 0) {
+            // Try broader search without company filter
+            if (includeCompany && filters.companyName) {
+                const broaderFilters = {
+                    firstName: filters.firstName,
+                    lastName: filters.lastName,
+                    limit: searchLimit,
+                };
+                const broaderResponse = await client.search(broaderFilters);
+                if (broaderResponse.success && broaderResponse.data.list.length > 0) {
+                    result.allCandidates = broaderResponse.data.list;
+                    result.totalCandidatesFound = broaderResponse.data.total_count;
+                }
+            }
+            if (result.allCandidates.length === 0) {
+                result.error = 'No candidates found in SmartProspect';
+                return result;
+            }
+        }
+        // Step 2: Find best match using intelligent matching
+        const matchResult = findBestMatch(linkedInContact, result.allCandidates, { minConfidence, fuzzyNames, fuzzyCompany });
+        if (!matchResult) {
+            result.error = `No match above ${minConfidence}% confidence threshold`;
+            return result;
+        }
+        result.matchedContact = matchResult.smartProspectContact;
+        result.matchConfidence = matchResult.confidence;
+        result.matchQuality = matchResult.quality;
+        result.matchedFields = matchResult.matchedFields;
+        // Step 3: Fetch email if auto-fetch enabled and good match (COSTS CREDITS)
+        if (autoFetch && matchResult.confidence >= minConfidence) {
+            const fetchResponse = await client.fetch([matchResult.smartProspectContact.id]);
+            if (fetchResponse.success && fetchResponse.data.list.length > 0) {
+                const enrichedContact = fetchResponse.data.list[0];
+                result.email = enrichedContact.email || null;
+                result.emailDeliverability = enrichedContact.emailDeliverability || 0;
+                result.verificationStatus = enrichedContact.verificationStatus || null;
+                // Update matched contact with enriched data
+                result.matchedContact = enrichedContact;
+            }
+        }
+        result.success = true;
+        return result;
+    }
+    catch (err) {
+        result.error = err instanceof Error ? err.message : 'Unknown error';
+        return result;
+    }
+}
+/**
+ * Enrich multiple LinkedIn contacts in batch
+ *
+ * Processes contacts sequentially to avoid rate limits.
+ * For parallel processing, use Promise.all with rate limiting.
+ */
+async function enrichLinkedInContactsBatch(linkedInContacts, smartProspectConfig, options = {}) {
+    const { delayMs = 200, onProgress, ...enrichOptions } = options;
+    const results = [];
+    for (let i = 0; i < linkedInContacts.length; i++) {
+        const contact = linkedInContacts[i];
+        const result = await enrichLinkedInContact(contact, smartProspectConfig, enrichOptions);
+        results.push(result);
+        if (onProgress) {
+            onProgress(i + 1, linkedInContacts.length, result);
+        }
+        // Delay between requests (except for last one)
+        if (i < linkedInContacts.length - 1 && delayMs > 0) {
+            await new Promise((r) => setTimeout(r, delayMs));
+        }
+    }
+    return results;
+}
+/**
+ * Create a reusable enricher function with pre-configured SmartProspect client
+ *
+ * More efficient for multiple enrichments as it reuses the same client/token.
+ *
+ * @example
+ * ```ts
+ * const enricher = createLinkedInEnricher({
+ *   email: process.env.SMARTLEAD_EMAIL,
+ *   password: process.env.SMARTLEAD_PASSWORD
+ * });
+ *
+ * // Now use for multiple contacts
+ * const result1 = await enricher.enrich(contact1);
+ * const result2 = await enricher.enrich(contact2);
+ *
+ * // Or batch
+ * const results = await enricher.enrichBatch([contact1, contact2, contact3]);
+ * ```
+ */
+function createLinkedInEnricher(smartProspectConfig, defaultOptions = {}) {
+    const client = (0, smartprospect_1.createSmartProspectClient)(smartProspectConfig);
+    if (!client) {
+        return null;
+    }
+    return {
+        client,
+        async enrich(contact, options = {}) {
+            const mergedOptions = { ...defaultOptions, ...options };
+            // We reuse the existing client rather than creating a new one
+            const result = {
+                success: false,
+                linkedInContact: contact,
+                matchedContact: null,
+                matchConfidence: 0,
+                matchQuality: 'none',
+                matchedFields: [],
+                email: null,
+                emailDeliverability: 0,
+                verificationStatus: null,
+                allCandidates: [],
+                totalCandidatesFound: 0,
+            };
+            const { minConfidence = 60, autoFetch = true, fuzzyNames = true, fuzzyCompany = true, searchLimit = 25, includeCompany = true, includeLocation = false, } = mergedOptions;
+            try {
+                const filters = buildSmartProspectFiltersFromLinkedIn(contact);
+                const searchFilters = {
+                    firstName: filters.firstName,
+                    lastName: filters.lastName,
+                    limit: searchLimit,
+                };
+                if (includeCompany && filters.companyName) {
+                    searchFilters.companyName = filters.companyName;
+                }
+                if (includeLocation && filters.country) {
+                    searchFilters.country = filters.country;
+                }
+                const searchResponse = await client.search(searchFilters);
+                if (!searchResponse.success) {
+                    result.error = `SmartProspect search failed: ${searchResponse.message}`;
+                    return result;
+                }
+                result.allCandidates = searchResponse.data.list;
+                result.totalCandidatesFound = searchResponse.data.total_count;
+                // Broader search fallback
+                if (searchResponse.data.list.length === 0 && includeCompany && filters.companyName) {
+                    const broaderResponse = await client.search({
+                        firstName: filters.firstName,
+                        lastName: filters.lastName,
+                        limit: searchLimit,
+                    });
+                    if (broaderResponse.success) {
+                        result.allCandidates = broaderResponse.data.list;
+                        result.totalCandidatesFound = broaderResponse.data.total_count;
+                    }
+                }
+                if (result.allCandidates.length === 0) {
+                    result.error = 'No candidates found in SmartProspect';
+                    return result;
+                }
+                const matchResult = findBestMatch(contact, result.allCandidates, {
+                    minConfidence,
+                    fuzzyNames,
+                    fuzzyCompany,
+                });
+                if (!matchResult) {
+                    result.error = `No match above ${minConfidence}% confidence threshold`;
+                    return result;
+                }
+                result.matchedContact = matchResult.smartProspectContact;
+                result.matchConfidence = matchResult.confidence;
+                result.matchQuality = matchResult.quality;
+                result.matchedFields = matchResult.matchedFields;
+                if (autoFetch && matchResult.confidence >= minConfidence) {
+                    const fetchResponse = await client.fetch([matchResult.smartProspectContact.id]);
+                    if (fetchResponse.success && fetchResponse.data.list.length > 0) {
+                        const enrichedContact = fetchResponse.data.list[0];
+                        result.email = enrichedContact.email || null;
+                        result.emailDeliverability = enrichedContact.emailDeliverability || 0;
+                        result.verificationStatus = enrichedContact.verificationStatus || null;
+                        result.matchedContact = enrichedContact;
+                    }
+                }
+                result.success = true;
+                return result;
+            }
+            catch (err) {
+                result.error = err instanceof Error ? err.message : 'Unknown error';
+                return result;
+            }
+        },
+        async enrichBatch(contacts, options = {}) {
+            const { delayMs = 200, onProgress, ...enrichOptions } = options;
+            const results = [];
+            for (let i = 0; i < contacts.length; i++) {
+                const result = await this.enrich(contacts[i], enrichOptions);
+                results.push(result);
+                if (onProgress) {
+                    onProgress(i + 1, contacts.length, result);
+                }
+                if (i < contacts.length - 1 && delayMs > 0) {
+                    await new Promise((r) => setTimeout(r, delayMs));
+                }
+            }
+            return results;
+        },
+        async searchOnly(contact, options = {}) {
+            const { searchLimit = 25, includeCompany = true } = options;
+            const filters = buildSmartProspectFiltersFromLinkedIn(contact);
+            const searchFilters = {
+                firstName: filters.firstName,
+                lastName: filters.lastName,
+                limit: searchLimit,
+            };
+            if (includeCompany && filters.companyName) {
+                searchFilters.companyName = filters.companyName;
+            }
+            const searchResponse = await client.search(searchFilters);
+            const candidates = searchResponse.success ? searchResponse.data.list : [];
+            const bestMatch = candidates.length > 0
+                ? findBestMatch(contact, candidates, { minConfidence: 0 })
+                : null;
+            return { candidates, bestMatch };
+        },
+        async fetchEmail(contactId) {
+            return client.fetch([contactId]);
+        },
+    };
+}

package/dist/enrichment/orchestrator.d.ts

@@ -4,7 +4,7 @@
  * Runs providers in sequence until a verified email is found that meets
  * the confidence threshold. Supports budget tracking and cost callbacks.
  */
-import type { CanonicalEmail, EnrichmentCandidate, ProviderFunc, BatchEnrichmentOptions, CostCallback, EnrichmentLogger } from './types';
+import type { CanonicalEmail, EnrichmentCandidate, ProviderFunc, BatchEnrichmentOptions, CostCallback, EnrichmentLogger, MultiEmailResult } from './types';
 export interface OrchestratorOptions {
     /** Provider functions in order */
     providers: ProviderFunc[];
@@ -29,3 +29,15 @@ export declare function enrichBusinessEmail(candidate: EnrichmentCandidate, opti
 export declare function enrichBatch(candidates: EnrichmentCandidate[], options: OrchestratorOptions & BatchEnrichmentOptions): Promise<Array<{
     candidate: EnrichmentCandidate;
 } & CanonicalEmail>>;
+/**
+ * Enrich a candidate and collect ALL emails from ALL providers
+ *
+ * Unlike enrichBusinessEmail which stops at the first valid match,
+ * this function queries all providers (respecting budget) and returns
+ * all found emails with their scores and classifications.
+ */
+export declare function enrichAllEmails(candidate: EnrichmentCandidate, options: OrchestratorOptions): Promise<MultiEmailResult>;
+/**
+ * Enrich multiple candidates and collect all emails (batch version)
+ */
+export declare function enrichAllBatch(candidates: EnrichmentCandidate[], options: OrchestratorOptions & BatchEnrichmentOptions): Promise<MultiEmailResult[]>;