linkedin-secret-sauce 0.5.1 → 0.6.0

package/dist/enrichment/auth/index.d.ts

@@ -1,4 +1,4 @@
 /**
  * Authentication modules for enrichment providers
  */
-export { getSmartLeadToken, getSmartLeadUser, clearSmartLeadToken, clearAllSmartLeadTokens, getSmartLeadTokenCacheStats, type SmartLeadCredentials, type SmartLeadAuthConfig, type SmartLeadUser, type SmartLeadLoginResponse, } from './smartlead-auth';
+export { getSmartLeadToken, getSmartLeadUser, clearSmartLeadToken, clearAllSmartLeadTokens, getSmartLeadTokenCacheStats, enableFileCache, disableFileCache, isFileCacheEnabled, clearFileCache, type SmartLeadCredentials, type SmartLeadAuthConfig, type SmartLeadUser, type SmartLeadLoginResponse, } from './smartlead-auth';

package/dist/enrichment/auth/index.js

@@ -3,10 +3,15 @@
  * Authentication modules for enrichment providers
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.getSmartLeadTokenCacheStats = exports.clearAllSmartLeadTokens = exports.clearSmartLeadToken = exports.getSmartLeadUser = exports.getSmartLeadToken = void 0;
+exports.clearFileCache = exports.isFileCacheEnabled = exports.disableFileCache = exports.enableFileCache = exports.getSmartLeadTokenCacheStats = exports.clearAllSmartLeadTokens = exports.clearSmartLeadToken = exports.getSmartLeadUser = exports.getSmartLeadToken = void 0;
 var smartlead_auth_1 = require("./smartlead-auth");
 Object.defineProperty(exports, "getSmartLeadToken", { enumerable: true, get: function () { return smartlead_auth_1.getSmartLeadToken; } });
 Object.defineProperty(exports, "getSmartLeadUser", { enumerable: true, get: function () { return smartlead_auth_1.getSmartLeadUser; } });
 Object.defineProperty(exports, "clearSmartLeadToken", { enumerable: true, get: function () { return smartlead_auth_1.clearSmartLeadToken; } });
 Object.defineProperty(exports, "clearAllSmartLeadTokens", { enumerable: true, get: function () { return smartlead_auth_1.clearAllSmartLeadTokens; } });
 Object.defineProperty(exports, "getSmartLeadTokenCacheStats", { enumerable: true, get: function () { return smartlead_auth_1.getSmartLeadTokenCacheStats; } });
+// File cache utilities for development/testing
+Object.defineProperty(exports, "enableFileCache", { enumerable: true, get: function () { return smartlead_auth_1.enableFileCache; } });
+Object.defineProperty(exports, "disableFileCache", { enumerable: true, get: function () { return smartlead_auth_1.disableFileCache; } });
+Object.defineProperty(exports, "isFileCacheEnabled", { enumerable: true, get: function () { return smartlead_auth_1.isFileCacheEnabled; } });
+Object.defineProperty(exports, "clearFileCache", { enumerable: true, get: function () { return smartlead_auth_1.clearFileCache; } });

package/dist/enrichment/auth/smartlead-auth.d.ts

@@ -3,6 +3,9 @@
  *
  * Handles JWT token acquisition via email/password login.
  * Tokens are cached in-memory with automatic refresh before expiry.
+ *
+ * For development/testing, file-based caching is supported to avoid
+ * repeated logins during test runs. Enable via `enableFileCache()`.
  */
 export interface SmartLeadCredentials {
     email: string;
@@ -47,4 +50,33 @@ export declare function clearAllSmartLeadTokens(): void;
 export declare function getSmartLeadTokenCacheStats(): {
     cachedEmails: string[];
     totalCached: number;
+    fileCacheEnabled: boolean;
+    fileCachePath: string | null;
 };
+/**
+ * Enable file-based token caching for development/testing
+ *
+ * When enabled, tokens are persisted to ~/.smartlead-tokens.json
+ * This avoids repeated logins during test development.
+ *
+ * @example
+ * ```ts
+ * // In your test setup
+ * import { enableFileCache } from 'linkedin-secret-sauce/enrichment';
+ *
+ * enableFileCache(); // Now tokens persist between test runs
+ * ```
+ */
+export declare function enableFileCache(): void;
+/**
+ * Disable file-based token caching
+ */
+export declare function disableFileCache(): void;
+/**
+ * Check if file cache is enabled
+ */
+export declare function isFileCacheEnabled(): boolean;
+/**
+ * Clear the file cache
+ */
+export declare function clearFileCache(): void;

package/dist/enrichment/auth/smartlead-auth.js

@@ -4,13 +4,56 @@
  *
  * Handles JWT token acquisition via email/password login.
  * Tokens are cached in-memory with automatic refresh before expiry.
+ *
+ * For development/testing, file-based caching is supported to avoid
+ * repeated logins during test runs. Enable via `enableFileCache()`.
  */
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.getSmartLeadToken = getSmartLeadToken;
 exports.getSmartLeadUser = getSmartLeadUser;
 exports.clearSmartLeadToken = clearSmartLeadToken;
 exports.clearAllSmartLeadTokens = clearAllSmartLeadTokens;
 exports.getSmartLeadTokenCacheStats = getSmartLeadTokenCacheStats;
+exports.enableFileCache = enableFileCache;
+exports.disableFileCache = disableFileCache;
+exports.isFileCacheEnabled = isFileCacheEnabled;
+exports.clearFileCache = clearFileCache;
+const fs = __importStar(require("fs"));
+const path = __importStar(require("path"));
+const os = __importStar(require("os"));
 const DEFAULT_LOGIN_URL = 'https://server.smartlead.ai/api/auth/login';
 const DEFAULT_REFRESH_BUFFER_MS = 5 * 60 * 1000; // 5 minutes
 const TOKEN_LIFETIME_MS = 24 * 60 * 60 * 1000; // Assume 24h JWT lifetime (conservative)
@@ -152,5 +195,127 @@ function getSmartLeadTokenCacheStats() {
     return {
         cachedEmails: Array.from(tokenCache.keys()),
         totalCached: tokenCache.size,
+        fileCacheEnabled,
+        fileCachePath: fileCacheEnabled ? getFileCachePath() : null,
     };
 }
+// =============================================================================
+// File-based Token Cache (for development/testing)
+// =============================================================================
+let fileCacheEnabled = false;
+const FILE_CACHE_NAME = '.smartlead-tokens.json';
+/**
+ * Get the file cache path
+ */
+function getFileCachePath() {
+    // Store in user's home directory or temp
+    const homeDir = os.homedir();
+    return path.join(homeDir, FILE_CACHE_NAME);
+}
+/**
+ * Load tokens from file cache
+ */
+function loadFileCache() {
+    const cache = new Map();
+    if (!fileCacheEnabled)
+        return cache;
+    try {
+        const filePath = getFileCachePath();
+        if (fs.existsSync(filePath)) {
+            const content = fs.readFileSync(filePath, 'utf8');
+            const data = JSON.parse(content);
+            for (const [key, value] of Object.entries(data)) {
+                // Validate structure
+                if (value && value.token && value.expiresAt && value.obtainedAt) {
+                    cache.set(key, value);
+                }
+            }
+        }
+    }
+    catch {
+        // Ignore file read errors
+    }
+    return cache;
+}
+/**
+ * Save tokens to file cache
+ */
+function saveFileCache() {
+    if (!fileCacheEnabled)
+        return;
+    try {
+        const filePath = getFileCachePath();
+        const data = {};
+        for (const [key, value] of tokenCache.entries()) {
+            data[key] = value;
+        }
+        fs.writeFileSync(filePath, JSON.stringify(data, null, 2), 'utf8');
+    }
+    catch {
+        // Ignore file write errors
+    }
+}
+/**
+ * Enable file-based token caching for development/testing
+ *
+ * When enabled, tokens are persisted to ~/.smartlead-tokens.json
+ * This avoids repeated logins during test development.
+ *
+ * @example
+ * ```ts
+ * // In your test setup
+ * import { enableFileCache } from 'linkedin-secret-sauce/enrichment';
+ *
+ * enableFileCache(); // Now tokens persist between test runs
+ * ```
+ */
+function enableFileCache() {
+    fileCacheEnabled = true;
+    // Load existing tokens from file into memory cache
+    const fileTokens = loadFileCache();
+    for (const [key, value] of fileTokens.entries()) {
+        // Only load if not already in memory and still valid
+        if (!tokenCache.has(key) && isTokenValid(value, DEFAULT_REFRESH_BUFFER_MS)) {
+            tokenCache.set(key, value);
+        }
+    }
+}
+/**
+ * Disable file-based token caching
+ */
+function disableFileCache() {
+    fileCacheEnabled = false;
+}
+/**
+ * Check if file cache is enabled
+ */
+function isFileCacheEnabled() {
+    return fileCacheEnabled;
+}
+/**
+ * Clear the file cache
+ */
+function clearFileCache() {
+    try {
+        const filePath = getFileCachePath();
+        if (fs.existsSync(filePath)) {
+            fs.unlinkSync(filePath);
+        }
+    }
+    catch {
+        // Ignore errors
+    }
+}
+// Patch the existing getSmartLeadToken to save to file cache after login
+const originalGetSmartLeadToken = getSmartLeadToken;
+// We need to modify the token caching behavior to persist to file
+// This is done by wrapping the cache set operation
+// Override tokenCache.set to also persist to file
+const originalSet = tokenCache.set.bind(tokenCache);
+tokenCache.set = function (key, value) {
+    const result = originalSet(key, value);
+    if (fileCacheEnabled) {
+        saveFileCache();
+    }
+    return result;
+};

package/dist/enrichment/index.d.ts

@@ -40,5 +40,7 @@ export { isDisposableEmail, isDisposableDomain, DISPOSABLE_DOMAINS, } from "./ut
 export { isValidEmailSyntax, isRoleAccount, asciiFold, cleanNamePart, hostnameFromUrl, extractLinkedInUsername, } from "./utils/validation";
 export { verifyEmailMx } from "./verification/mx";
 export { createConstructProvider, createLddProvider, createSmartProspectProvider, createHunterProvider, createApolloProvider, createDropcontactProvider, } from "./providers";
-export { enrichBusinessEmail, enrichBatch } from "./orchestrator";
-export { getSmartLeadToken, getSmartLeadUser, clearSmartLeadToken, clearAllSmartLeadTokens, getSmartLeadTokenCacheStats, type SmartLeadCredentials, type SmartLeadAuthConfig, type SmartLeadUser, type SmartLeadLoginResponse, } from "./auth";
+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";

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.getSmartLeadTokenCacheStats = exports.clearAllSmartLeadTokens = exports.clearSmartLeadToken = exports.getSmartLeadUser = exports.getSmartLeadToken = exports.enrichBatch = exports.enrichBusinessEmail = 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.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.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");
@@ -154,6 +154,25 @@ function createEnrichmentClient(config) {
                 ...batchOptions,
             });
         },
+        /**
+         * Enrich a single candidate and return ALL found emails from ALL providers
+         *
+         * Unlike `enrich()` which returns the first valid business email,
+         * this method queries all providers and returns every email found,
+         * including personal emails, with type classifications and scores.
+         */
+        async enrichAll(candidate) {
+            return (0, orchestrator_1.enrichAllEmails)(candidate, orchestratorOptions);
+        },
+        /**
+         * Enrich multiple candidates and return ALL found emails for each
+         */
+        async enrichAllBatch(candidates, batchOptions) {
+            return (0, orchestrator_1.enrichAllBatch)(candidates, {
+                ...orchestratorOptions,
+                ...batchOptions,
+            });
+        },
     };
 }
 /**
@@ -231,10 +250,15 @@ Object.defineProperty(exports, "createSmartProspectProvider", { enumerable: true
 Object.defineProperty(exports, "createHunterProvider", { enumerable: true, get: function () { return providers_1.createHunterProvider; } });
 Object.defineProperty(exports, "createApolloProvider", { enumerable: true, get: function () { return providers_1.createApolloProvider; } });
 Object.defineProperty(exports, "createDropcontactProvider", { enumerable: true, get: function () { return providers_1.createDropcontactProvider; } });
+// Re-export SmartProspect client for direct API access
+var smartprospect_2 = require("./providers/smartprospect");
+Object.defineProperty(exports, "createSmartProspectClient", { enumerable: true, get: function () { return smartprospect_2.createSmartProspectClient; } });
 // Re-export orchestrator (for advanced usage)
 var orchestrator_2 = require("./orchestrator");
 Object.defineProperty(exports, "enrichBusinessEmail", { enumerable: true, get: function () { return orchestrator_2.enrichBusinessEmail; } });
 Object.defineProperty(exports, "enrichBatch", { enumerable: true, get: function () { return orchestrator_2.enrichBatch; } });
+Object.defineProperty(exports, "enrichAllEmails", { enumerable: true, get: function () { return orchestrator_2.enrichAllEmails; } });
+Object.defineProperty(exports, "enrichAllBatch", { enumerable: true, get: function () { return orchestrator_2.enrichAllBatch; } });
 // Re-export auth utilities (for advanced usage)
 var auth_1 = require("./auth");
 Object.defineProperty(exports, "getSmartLeadToken", { enumerable: true, get: function () { return auth_1.getSmartLeadToken; } });
@@ -242,3 +266,21 @@ Object.defineProperty(exports, "getSmartLeadUser", { enumerable: true, get: func
 Object.defineProperty(exports, "clearSmartLeadToken", { enumerable: true, get: function () { return auth_1.clearSmartLeadToken; } });
 Object.defineProperty(exports, "clearAllSmartLeadTokens", { enumerable: true, get: function () { return auth_1.clearAllSmartLeadTokens; } });
 Object.defineProperty(exports, "getSmartLeadTokenCacheStats", { enumerable: true, get: function () { return auth_1.getSmartLeadTokenCacheStats; } });
+// File cache utilities for development/testing
+Object.defineProperty(exports, "enableFileCache", { enumerable: true, get: function () { return auth_1.enableFileCache; } });
+Object.defineProperty(exports, "disableFileCache", { enumerable: true, get: function () { return auth_1.disableFileCache; } });
+Object.defineProperty(exports, "isFileCacheEnabled", { enumerable: true, get: function () { return auth_1.isFileCacheEnabled; } });
+Object.defineProperty(exports, "clearFileCache", { enumerable: true, get: function () { return auth_1.clearFileCache; } });
+// Re-export matching utilities (LinkedIn <-> SmartProspect)
+var matching_1 = require("./matching");
+// Low-level matching functions
+Object.defineProperty(exports, "calculateMatchConfidence", { enumerable: true, get: function () { return matching_1.calculateMatchConfidence; } });
+Object.defineProperty(exports, "classifyMatchQuality", { enumerable: true, get: function () { return matching_1.classifyMatchQuality; } });
+Object.defineProperty(exports, "findBestMatch", { enumerable: true, get: function () { return matching_1.findBestMatch; } });
+Object.defineProperty(exports, "matchContacts", { enumerable: true, get: function () { return matching_1.matchContacts; } });
+Object.defineProperty(exports, "buildSmartProspectFiltersFromLinkedIn", { enumerable: true, get: function () { return matching_1.buildSmartProspectFiltersFromLinkedIn; } });
+Object.defineProperty(exports, "parseLinkedInSearchResponse", { enumerable: true, get: function () { return matching_1.parseLinkedInSearchResponse; } });
+// High-level enrichment functions
+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; } });

package/dist/enrichment/matching.d.ts

@@ -0,0 +1,239 @@
+/**
+ * Contact Matching Utilities
+ *
+ * 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 SmartProspectClient } from './providers/smartprospect';
+/**
+ * LinkedIn Sales Navigator contact (simplified from API response)
+ */
+export interface LinkedInContact {
+    /** LinkedIn member URN (e.g., "urn:li:member:1044675597") */
+    objectUrn?: string;
+    /** Sales Nav entity URN */
+    entityUrn?: string;
+    firstName: string;
+    lastName: string;
+    fullName?: string;
+    /** Geographic region (e.g., "Sofia, Sofia City, Bulgaria") */
+    geoRegion?: string;
+    /** Current positions array */
+    currentPositions?: Array<{
+        companyName?: string;
+        title?: string;
+        companyUrn?: string;
+        companyUrnResolutionResult?: {
+            name?: string;
+            website?: string;
+            industry?: string;
+            location?: string;
+        };
+    }>;
+    /** Profile picture */
+    profilePictureDisplayImage?: {
+        rootUrl?: string;
+        artifacts?: Array<{
+            fileIdentifyingUrlPathSegment?: string;
+        }>;
+    };
+}
+/**
+ * Match result with confidence score
+ */
+export interface MatchResult {
+    /** The matched SmartProspect contact */
+    smartProspectContact: SmartProspectContact;
+    /** The LinkedIn contact that was matched */
+    linkedInContact: LinkedInContact;
+    /** Match confidence score (0-100) */
+    confidence: number;
+    /** Which fields matched */
+    matchedFields: string[];
+    /** Match quality classification */
+    quality: 'exact' | 'high' | 'medium' | 'low' | 'none';
+}
+/**
+ * Options for matching
+ */
+export interface MatchOptions {
+    /** Minimum confidence threshold (default: 50) */
+    minConfidence?: number;
+    /** Whether to use fuzzy matching for names (default: true) */
+    fuzzyNames?: boolean;
+    /** Whether to use fuzzy matching for company names (default: true) */
+    fuzzyCompany?: boolean;
+}
+/**
+ * Calculate match confidence between a LinkedIn contact and SmartProspect contact
+ */
+export declare function calculateMatchConfidence(linkedin: LinkedInContact, smartprospect: SmartProspectContact, options?: MatchOptions): {
+    confidence: number;
+    matchedFields: string[];
+};
+/**
+ * Classify match quality based on confidence and matched fields
+ */
+export declare function classifyMatchQuality(confidence: number, matchedFields: string[]): 'exact' | 'high' | 'medium' | 'low' | 'none';
+/**
+ * Find the best matching SmartProspect contact for a LinkedIn contact
+ */
+export declare function findBestMatch(linkedInContact: LinkedInContact, smartProspectContacts: SmartProspectContact[], options?: MatchOptions): MatchResult | null;
+/**
+ * Match multiple LinkedIn contacts to SmartProspect contacts
+ */
+export declare function matchContacts(linkedInContacts: LinkedInContact[], smartProspectContacts: SmartProspectContact[], options?: MatchOptions): MatchResult[];
+/**
+ * Build SmartProspect search filters from a LinkedIn contact
+ * This helps you search SmartProspect for a specific LinkedIn contact
+ */
+export declare function buildSmartProspectFiltersFromLinkedIn(linkedInContact: LinkedInContact): {
+    firstName: string[];
+    lastName: string[];
+    companyName?: string[];
+    title?: string[];
+    country?: string[];
+};
+/**
+ * Parse LinkedIn Sales Navigator API response elements into LinkedInContact array
+ */
+export declare function parseLinkedInSearchResponse(elements: Array<Record<string, unknown>>): LinkedInContact[];
+/**
+ * Result of enriching a LinkedIn contact via SmartProspect
+ */
+export interface LinkedInEnrichmentResult {
+    /** Whether enrichment was successful */
+    success: boolean;
+    /** The original LinkedIn contact */
+    linkedInContact: LinkedInContact;
+    /** The matched SmartProspect contact (if found) */
+    matchedContact: SmartProspectContact | null;
+    /** Match confidence score (0-100) */
+    matchConfidence: number;
+    /** Match quality classification */
+    matchQuality: 'exact' | 'high' | 'medium' | 'low' | 'none';
+    /** Which fields matched */
+    matchedFields: string[];
+    /** Enriched email (if fetched) */
+    email: string | null;
+    /** Email deliverability score (0-1) */
+    emailDeliverability: number;
+    /** Email verification status */
+    verificationStatus: string | null;
+    /** All candidate contacts found in SmartProspect */
+    allCandidates: SmartProspectContact[];
+    /** Total candidates found in search */
+    totalCandidatesFound: number;
+    /** Error message if failed */
+    error?: string;
+}
+/**
+ * Options for LinkedIn contact enrichment
+ */
+export interface LinkedInEnrichmentOptions {
+    /** Minimum match confidence to consider (default: 60) */
+    minConfidence?: number;
+    /** Whether to auto-fetch email if good match found (default: true) - COSTS CREDITS */
+    autoFetch?: boolean;
+    /** Whether to use fuzzy name matching (default: true) */
+    fuzzyNames?: boolean;
+    /** Whether to use fuzzy company matching (default: true) */
+    fuzzyCompany?: boolean;
+    /** Search limit - how many candidates to retrieve (default: 25) */
+    searchLimit?: number;
+    /** Whether to include company name in search (default: true) */
+    includeCompany?: boolean;
+    /** Whether to include location in search (default: false) */
+    includeLocation?: boolean;
+}
+/**
+ * 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}%`);
+ * }
+ * ```
+ */
+export declare function enrichLinkedInContact(linkedInContact: LinkedInContact, smartProspectConfig: SmartProspectConfig, options?: LinkedInEnrichmentOptions): Promise<LinkedInEnrichmentResult>;
+/**
+ * Enrich multiple LinkedIn contacts in batch
+ *
+ * Processes contacts sequentially to avoid rate limits.
+ * For parallel processing, use Promise.all with rate limiting.
+ */
+export declare function enrichLinkedInContactsBatch(linkedInContacts: LinkedInContact[], smartProspectConfig: SmartProspectConfig, options?: LinkedInEnrichmentOptions & {
+    /** Delay between requests in ms (default: 200) */
+    delayMs?: number;
+    /** Callback for progress updates */
+    onProgress?: (completed: number, total: number, result: LinkedInEnrichmentResult) => void;
+}): Promise<LinkedInEnrichmentResult[]>;
+/**
+ * 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]);
+ * ```
+ */
+export declare function createLinkedInEnricher(smartProspectConfig: SmartProspectConfig, defaultOptions?: LinkedInEnrichmentOptions): {
+    /** The underlying SmartProspect client */
+    client: SmartProspectClient;
+    /** Enrich a single LinkedIn contact */
+    enrich: (contact: LinkedInContact, options?: LinkedInEnrichmentOptions) => Promise<LinkedInEnrichmentResult>;
+    /** Enrich multiple LinkedIn contacts */
+    enrichBatch: (contacts: LinkedInContact[], options?: LinkedInEnrichmentOptions & {
+        delayMs?: number;
+        onProgress?: (completed: number, total: number, result: LinkedInEnrichmentResult) => void;
+    }) => Promise<LinkedInEnrichmentResult[]>;
+    /** Search SmartProspect for a LinkedIn contact without fetching (FREE) */
+    searchOnly: (contact: LinkedInContact, options?: {
+        searchLimit?: number;
+        includeCompany?: boolean;
+    }) => Promise<{
+        candidates: SmartProspectContact[];
+        bestMatch: MatchResult | null;
+    }>;
+    /** Fetch email for a specific SmartProspect contact ID (COSTS CREDITS) */
+    fetchEmail: (contactId: string) => Promise<SmartProspectFetchResponse>;
+} | null;