linkedin-secret-sauce 0.5.0 → 0.6.0

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;