linkedin-secret-sauce 0.7.2 → 0.8.0

package/dist/enrichment/index.d.ts

@@ -44,4 +44,4 @@ export { extractNumericLinkedInId } from "./providers/ldd";
 export { createSmartProspectClient, type SmartProspectClient, type SmartProspectLocationOptions, } from "./providers/smartprospect";
 export { enrichBusinessEmail, enrichBatch, enrichAllEmails, enrichAllBatch } from "./orchestrator";
 export { getSmartLeadToken, getSmartLeadUser, clearSmartLeadToken, clearAllSmartLeadTokens, getSmartLeadTokenCacheStats, enableFileCache, disableFileCache, isFileCacheEnabled, clearFileCache, type SmartLeadCredentials, type SmartLeadAuthConfig, type SmartLeadUser, type SmartLeadLoginResponse, } from "./auth";
-export { calculateMatchConfidence, classifyMatchQuality, findBestMatch, matchContacts, buildSmartProspectFiltersFromLinkedIn, parseLinkedInSearchResponse, enrichLinkedInContact, enrichLinkedInContactsBatch, createLinkedInEnricher, type LinkedInContact, type MatchResult, type MatchOptions, type LinkedInEnrichmentResult, type LinkedInEnrichmentOptions, } from "./matching";
+export { calculateMatchConfidence, classifyMatchQuality, findBestMatch, matchContacts, buildSmartProspectFiltersFromLinkedIn, parseLinkedInSearchResponse, enrichLinkedInContact, enrichLinkedInContactsBatch, createLinkedInEnricher, getEmailsForLinkedInContact, getEmailsForLinkedInContactsBatch, type LinkedInContact, type MatchResult, type MatchOptions, type LinkedInEnrichmentResult, type LinkedInEnrichmentOptions, type EmailResult, type GetEmailsResult, type GetEmailsConfig, type GetEmailsOptions, } from "./matching";

package/dist/enrichment/index.js

@@ -42,7 +42,7 @@ var __exportStar = (this && this.__exportStar) || function(m, exports) {
     for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.createLinkedInEnricher = exports.enrichLinkedInContactsBatch = exports.enrichLinkedInContact = exports.parseLinkedInSearchResponse = exports.buildSmartProspectFiltersFromLinkedIn = exports.matchContacts = exports.findBestMatch = exports.classifyMatchQuality = exports.calculateMatchConfidence = exports.clearFileCache = exports.isFileCacheEnabled = exports.disableFileCache = exports.enableFileCache = exports.getSmartLeadTokenCacheStats = exports.clearAllSmartLeadTokens = exports.clearSmartLeadToken = exports.getSmartLeadUser = exports.getSmartLeadToken = exports.enrichAllBatch = exports.enrichAllEmails = exports.enrichBatch = exports.enrichBusinessEmail = exports.createSmartProspectClient = exports.extractNumericLinkedInId = exports.createDropcontactProvider = exports.createApolloProvider = exports.createHunterProvider = exports.createSmartProspectProvider = exports.createLddProvider = exports.createConstructProvider = exports.verifyEmailMx = exports.extractLinkedInUsername = exports.hostnameFromUrl = exports.cleanNamePart = exports.asciiFold = exports.isRoleAccount = exports.isValidEmailSyntax = exports.DISPOSABLE_DOMAINS = exports.isDisposableDomain = exports.isDisposableEmail = exports.PERSONAL_DOMAINS = exports.isPersonalDomain = exports.isBusinessEmail = exports.isPersonalEmail = void 0;
+exports.getEmailsForLinkedInContactsBatch = exports.getEmailsForLinkedInContact = exports.createLinkedInEnricher = exports.enrichLinkedInContactsBatch = exports.enrichLinkedInContact = exports.parseLinkedInSearchResponse = exports.buildSmartProspectFiltersFromLinkedIn = exports.matchContacts = exports.findBestMatch = exports.classifyMatchQuality = exports.calculateMatchConfidence = exports.clearFileCache = exports.isFileCacheEnabled = exports.disableFileCache = exports.enableFileCache = exports.getSmartLeadTokenCacheStats = exports.clearAllSmartLeadTokens = exports.clearSmartLeadToken = exports.getSmartLeadUser = exports.getSmartLeadToken = exports.enrichAllBatch = exports.enrichAllEmails = exports.enrichBatch = exports.enrichBusinessEmail = exports.createSmartProspectClient = exports.extractNumericLinkedInId = exports.createDropcontactProvider = exports.createApolloProvider = exports.createHunterProvider = exports.createSmartProspectProvider = exports.createLddProvider = exports.createConstructProvider = exports.verifyEmailMx = exports.extractLinkedInUsername = exports.hostnameFromUrl = exports.cleanNamePart = exports.asciiFold = exports.isRoleAccount = exports.isValidEmailSyntax = exports.DISPOSABLE_DOMAINS = exports.isDisposableDomain = exports.isDisposableEmail = exports.PERSONAL_DOMAINS = exports.isPersonalDomain = exports.isBusinessEmail = exports.isPersonalEmail = void 0;
 exports.createEnrichmentClient = createEnrichmentClient;
 const orchestrator_1 = require("./orchestrator");
 const construct_1 = require("./providers/construct");
@@ -287,3 +287,6 @@ Object.defineProperty(exports, "parseLinkedInSearchResponse", { enumerable: true
 Object.defineProperty(exports, "enrichLinkedInContact", { enumerable: true, get: function () { return matching_1.enrichLinkedInContact; } });
 Object.defineProperty(exports, "enrichLinkedInContactsBatch", { enumerable: true, get: function () { return matching_1.enrichLinkedInContactsBatch; } });
 Object.defineProperty(exports, "createLinkedInEnricher", { enumerable: true, get: function () { return matching_1.createLinkedInEnricher; } });
+// UNIFIED email lookup (recommended for most use cases)
+Object.defineProperty(exports, "getEmailsForLinkedInContact", { enumerable: true, get: function () { return matching_1.getEmailsForLinkedInContact; } });
+Object.defineProperty(exports, "getEmailsForLinkedInContactsBatch", { enumerable: true, get: function () { return matching_1.getEmailsForLinkedInContactsBatch; } });

package/dist/enrichment/matching.d.ts

@@ -4,7 +4,7 @@
  * Matches contacts between LinkedIn Sales Navigator and SmartProspect
  * to find the same person across both platforms.
  */
-import type { SmartProspectContact, SmartProspectConfig, SmartProspectFetchResponse } from './types';
+import type { SmartProspectContact, SmartProspectConfig, SmartProspectFetchResponse, LddConfig } from './types';
 import { type SmartProspectClient } from './providers/smartprospect';
 /**
  * LinkedIn Sales Navigator contact (simplified from API response)
@@ -239,3 +239,112 @@ export declare function createLinkedInEnricher(smartProspectConfig: SmartProspec
     /** Fetch email for a specific SmartProspect contact ID (COSTS CREDITS) */
     fetchEmail: (contactId: string) => Promise<SmartProspectFetchResponse>;
 } | null;
+/**
+ * Email result from unified lookup
+ */
+export interface EmailResult {
+    /** The email address */
+    email: string;
+    /** Which provider found this email */
+    source: 'ldd' | 'smartprospect';
+    /** Confidence score (0-100) */
+    confidence: number;
+    /** Email type classification */
+    type: 'business' | 'personal' | 'unknown';
+    /** Whether the email was verified */
+    verified: boolean;
+    /** Email deliverability score (0-1) for SmartProspect emails */
+    deliverability?: number;
+    /** Additional metadata */
+    metadata?: Record<string, unknown>;
+}
+/**
+ * Result from unified email lookup
+ */
+export interface GetEmailsResult {
+    /** Whether lookup was successful (found at least one email) */
+    success: boolean;
+    /** All found emails, sorted by confidence (highest first) */
+    emails: EmailResult[];
+    /** Numeric LinkedIn ID extracted from objectUrn */
+    numericLinkedInId: string | null;
+    /** Which providers were queried */
+    providersQueried: ('ldd' | 'smartprospect')[];
+    /** Error message if failed */
+    error?: string;
+}
+/**
+ * Configuration for unified email lookup
+ */
+export interface GetEmailsConfig {
+    /** LDD configuration (optional but recommended - FREE) */
+    ldd?: LddConfig;
+    /** SmartProspect configuration (optional - PAID fallback) */
+    smartprospect?: SmartProspectConfig;
+}
+/**
+ * Options for unified email lookup
+ */
+export interface GetEmailsOptions {
+    /** Skip LDD lookup (default: false) */
+    skipLdd?: boolean;
+    /** Skip SmartProspect lookup (default: false) */
+    skipSmartProspect?: boolean;
+    /** Minimum match confidence for SmartProspect (default: 60) */
+    minMatchConfidence?: number;
+    /** Include company in SmartProspect search (default: true) */
+    includeCompany?: boolean;
+}
+/**
+ * Get emails for a LinkedIn contact - UNIFIED FUNCTION
+ *
+ * This is the main function consumers should use. It:
+ * 1. Extracts the numeric LinkedIn ID from objectUrn (stable identifier)
+ * 2. Tries LDD first (FREE, uses numeric ID for reliable lookup)
+ * 3. Falls back to SmartProspect if LDD has no results (PAID)
+ * 4. Returns ALL emails with unified scoring
+ *
+ * @example
+ * ```ts
+ * import { getEmailsForLinkedInContact } from 'linkedin-secret-sauce';
+ *
+ * // From your LinkedIn Sales Nav search result
+ * const contact = {
+ *   objectUrn: 'urn:li:member:307567',  // IMPORTANT: Include this!
+ *   firstName: 'Jim',
+ *   lastName: 'DeMaio',
+ *   currentPositions: [{ companyName: 'Acme Corp', title: 'CEO' }]
+ * };
+ *
+ * const result = await getEmailsForLinkedInContact(contact, {
+ *   ldd: {
+ *     apiUrl: process.env.LDD_API_URL,
+ *     apiToken: process.env.LDD_API_TOKEN,
+ *   },
+ *   smartprospect: {
+ *     email: process.env.SMARTLEAD_EMAIL,
+ *     password: process.env.SMARTLEAD_PASSWORD,
+ *   },
+ * });
+ *
+ * if (result.success) {
+ *   console.log('Found emails:', result.emails);
+ *   // [
+ *   //   { email: 'jim@acme.com', source: 'ldd', confidence: 95, type: 'business' },
+ *   //   { email: 'jim@gmail.com', source: 'ldd', confidence: 70, type: 'personal' }
+ *   // ]
+ * }
+ * ```
+ */
+export declare function getEmailsForLinkedInContact(contact: LinkedInContact, config: GetEmailsConfig, options?: GetEmailsOptions): Promise<GetEmailsResult>;
+/**
+ * Get emails for multiple LinkedIn contacts in batch
+ *
+ * Processes contacts sequentially to avoid rate limits.
+ */
+export declare function getEmailsForLinkedInContactsBatch(contacts: LinkedInContact[], config: GetEmailsConfig, options?: GetEmailsOptions & {
+    /** Delay between requests in ms (default: 200) */
+    delayMs?: number;
+    /** Callback for progress updates */
+    onProgress?: (completed: number, total: number, result: GetEmailsResult) => void;
+}): Promise<GetEmailsResult[]>;

package/dist/enrichment/matching.js

@@ -15,6 +15,8 @@ exports.parseLinkedInSearchResponse = parseLinkedInSearchResponse;
 exports.enrichLinkedInContact = enrichLinkedInContact;
 exports.enrichLinkedInContactsBatch = enrichLinkedInContactsBatch;
 exports.createLinkedInEnricher = createLinkedInEnricher;
+exports.getEmailsForLinkedInContact = getEmailsForLinkedInContact;
+exports.getEmailsForLinkedInContactsBatch = getEmailsForLinkedInContactsBatch;
 const smartprospect_1 = require("./providers/smartprospect");
 const ldd_1 = require("./providers/ldd");
 // =============================================================================
@@ -624,3 +626,196 @@ function createLinkedInEnricher(smartProspectConfig, defaultOptions = {}) {
         },
     };
 }
+/**
+ * Get emails for a LinkedIn contact - UNIFIED FUNCTION
+ *
+ * This is the main function consumers should use. It:
+ * 1. Extracts the numeric LinkedIn ID from objectUrn (stable identifier)
+ * 2. Tries LDD first (FREE, uses numeric ID for reliable lookup)
+ * 3. Falls back to SmartProspect if LDD has no results (PAID)
+ * 4. Returns ALL emails with unified scoring
+ *
+ * @example
+ * ```ts
+ * import { getEmailsForLinkedInContact } from 'linkedin-secret-sauce';
+ *
+ * // From your LinkedIn Sales Nav search result
+ * const contact = {
+ *   objectUrn: 'urn:li:member:307567',  // IMPORTANT: Include this!
+ *   firstName: 'Jim',
+ *   lastName: 'DeMaio',
+ *   currentPositions: [{ companyName: 'Acme Corp', title: 'CEO' }]
+ * };
+ *
+ * const result = await getEmailsForLinkedInContact(contact, {
+ *   ldd: {
+ *     apiUrl: process.env.LDD_API_URL,
+ *     apiToken: process.env.LDD_API_TOKEN,
+ *   },
+ *   smartprospect: {
+ *     email: process.env.SMARTLEAD_EMAIL,
+ *     password: process.env.SMARTLEAD_PASSWORD,
+ *   },
+ * });
+ *
+ * if (result.success) {
+ *   console.log('Found emails:', result.emails);
+ *   // [
+ *   //   { email: 'jim@acme.com', source: 'ldd', confidence: 95, type: 'business' },
+ *   //   { email: 'jim@gmail.com', source: 'ldd', confidence: 70, type: 'personal' }
+ *   // ]
+ * }
+ * ```
+ */
+async function getEmailsForLinkedInContact(contact, config, options = {}) {
+    const { skipLdd = false, skipSmartProspect = false, minMatchConfidence = 60, includeCompany = true, } = options;
+    // Extract numeric ID from objectUrn
+    const numericLinkedInId = (0, ldd_1.extractNumericLinkedInId)(contact.objectUrn);
+    const result = {
+        success: false,
+        emails: [],
+        numericLinkedInId,
+        providersQueried: [],
+    };
+    // ==========================================================================
+    // Step 1: Try LDD first (FREE)
+    // ==========================================================================
+    if (!skipLdd && config.ldd?.apiUrl && config.ldd?.apiToken) {
+        result.providersQueried.push('ldd');
+        try {
+            const lddProvider = (0, ldd_1.createLddProvider)(config.ldd);
+            const lddResult = await lddProvider({
+                numericLinkedInId: numericLinkedInId || undefined,
+                linkedinUsername: undefined, // Let LDD provider extract from contact if needed
+                firstName: contact.firstName,
+                lastName: contact.lastName,
+            });
+            if (lddResult && 'emails' in lddResult && lddResult.emails.length > 0) {
+                // LDD found emails!
+                for (const emailData of lddResult.emails) {
+                    result.emails.push({
+                        email: emailData.email,
+                        source: 'ldd',
+                        confidence: emailData.confidence ?? 90,
+                        type: emailData.metadata?.emailTypeClassified || 'unknown',
+                        verified: emailData.verified ?? true,
+                        metadata: emailData.metadata,
+                    });
+                }
+                result.success = true;
+            }
+        }
+        catch (err) {
+            // LDD failed, continue to SmartProspect
+            result.error = `LDD error: ${err instanceof Error ? err.message : 'Unknown error'}`;
+        }
+    }
+    // ==========================================================================
+    // Step 2: Fall back to SmartProspect if LDD didn't find emails (PAID)
+    // ==========================================================================
+    if (!result.success && !skipSmartProspect && config.smartprospect) {
+        result.providersQueried.push('smartprospect');
+        try {
+            const client = (0, smartprospect_1.createSmartProspectClient)(config.smartprospect);
+            if (!client) {
+                result.error = 'Failed to create SmartProspect client';
+                return result;
+            }
+            // Build search filters
+            const filters = buildSmartProspectFiltersFromLinkedIn(contact);
+            const searchFilters = {
+                firstName: filters.firstName,
+                lastName: filters.lastName,
+                limit: 25,
+            };
+            if (includeCompany && filters.companyName) {
+                searchFilters.companyName = filters.companyName;
+            }
+            // Search for matching contacts
+            const searchResponse = await client.search(searchFilters);
+            if (!searchResponse.success || searchResponse.data.list.length === 0) {
+                // Try broader search without company
+                if (includeCompany && filters.companyName) {
+                    const broaderResponse = await client.search({
+                        firstName: filters.firstName,
+                        lastName: filters.lastName,
+                        limit: 25,
+                    });
+                    if (broaderResponse.success && broaderResponse.data.list.length > 0) {
+                        searchResponse.data.list = broaderResponse.data.list;
+                    }
+                }
+            }
+            if (searchResponse.data.list.length === 0) {
+                result.error = result.error
+                    ? `${result.error}; SmartProspect: No candidates found`
+                    : 'SmartProspect: No candidates found';
+                return result;
+            }
+            // Find best match
+            const matchResult = findBestMatch(contact, searchResponse.data.list, {
+                minConfidence: minMatchConfidence,
+                fuzzyNames: true,
+                fuzzyCompany: true,
+            });
+            if (!matchResult) {
+                result.error = result.error
+                    ? `${result.error}; SmartProspect: No match above ${minMatchConfidence}% confidence`
+                    : `SmartProspect: No match above ${minMatchConfidence}% confidence`;
+                return result;
+            }
+            // Fetch email for matched contact (COSTS CREDITS)
+            const fetchResponse = await client.fetch([matchResult.smartProspectContact.id]);
+            if (fetchResponse.success && fetchResponse.data.list.length > 0) {
+                const enrichedContact = fetchResponse.data.list[0];
+                if (enrichedContact.email) {
+                    result.emails.push({
+                        email: enrichedContact.email,
+                        source: 'smartprospect',
+                        confidence: matchResult.confidence,
+                        type: 'business', // SmartProspect returns business emails
+                        verified: enrichedContact.verificationStatus === 'verified',
+                        deliverability: enrichedContact.emailDeliverability,
+                        metadata: {
+                            matchQuality: matchResult.quality,
+                            matchedFields: matchResult.matchedFields,
+                            smartProspectId: enrichedContact.id,
+                            company: enrichedContact.company?.name,
+                            title: enrichedContact.title,
+                        },
+                    });
+                    result.success = true;
+                }
+            }
+        }
+        catch (err) {
+            result.error = result.error
+                ? `${result.error}; SmartProspect error: ${err instanceof Error ? err.message : 'Unknown error'}`
+                : `SmartProspect error: ${err instanceof Error ? err.message : 'Unknown error'}`;
+        }
+    }
+    // Sort emails by confidence (highest first)
+    result.emails.sort((a, b) => b.confidence - a.confidence);
+    return result;
+}
+/**
+ * Get emails for multiple LinkedIn contacts in batch
+ *
+ * Processes contacts sequentially to avoid rate limits.
+ */
+async function getEmailsForLinkedInContactsBatch(contacts, config, options = {}) {
+    const { delayMs = 200, onProgress, ...lookupOptions } = options;
+    const results = [];
+    for (let i = 0; i < contacts.length; i++) {
+        const result = await getEmailsForLinkedInContact(contacts[i], config, lookupOptions);
+        results.push(result);
+        if (onProgress) {
+            onProgress(i + 1, contacts.length, result);
+        }
+        // Delay between requests (except for last one)
+        if (i < contacts.length - 1 && delayMs > 0) {
+            await new Promise((r) => setTimeout(r, delayMs));
+        }
+    }
+    return results;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "linkedin-secret-sauce",
-  "version": "0.7.2",
+  "version": "0.8.0",
   "description": "Private LinkedIn Sales Navigator client with automatic cookie management",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",