linkedin-secret-sauce 0.5.1 → 0.7.1

package/dist/enrichment/providers/ldd.js

@@ -4,8 +4,13 @@
  *
  * YOUR private database of ~500M scraped LinkedIn profiles with emails.
  * This is FREE and unlimited - it's your own service.
+ *
+ * IMPORTANT: Prefer numeric LinkedIn ID over username for lookups.
+ * The numeric ID (from objectUrn like "urn:li:member:307567") is STABLE and never changes,
+ * while usernames can be changed by users at any time.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.extractNumericLinkedInId = extractNumericLinkedInId;
 exports.createLddProvider = createLddProvider;
 const validation_1 = require("../utils/validation");
 /**
@@ -45,6 +50,35 @@ async function requestWithRetry(url, token, retries = 1, backoffMs = 200) {
     }
     throw lastErr ?? new Error("ldd_http_error");
 }
+/**
+ * Extract numeric LinkedIn ID from various formats:
+ * - Direct number: "307567"
+ * - URN format: "urn:li:member:307567"
+ * - Full URN: "urn:li:fs_salesProfile:(ACwAAAAEsW8B...,NAME_SEARCH,PJOV)"
+ * - objectUrn: "urn:li:member:307567"
+ *
+ * Returns the numeric ID as a string, or null if not found.
+ */
+function extractNumericLinkedInId(input) {
+    if (!input)
+        return null;
+    const trimmed = input.trim();
+    // Direct numeric ID
+    if (/^\d+$/.test(trimmed)) {
+        return trimmed;
+    }
+    // URN format: urn:li:member:307567
+    const memberMatch = trimmed.match(/urn:li:member:(\d+)/i);
+    if (memberMatch) {
+        return memberMatch[1];
+    }
+    // Sales profile URN with numeric ID
+    const salesMatch = trimmed.match(/urn:li:fs_salesProfile:\((\d+),/i);
+    if (salesMatch) {
+        return salesMatch[1];
+    }
+    return null;
+}
 /**
  * Extract LinkedIn username from candidate
  */
@@ -62,8 +96,43 @@ function extractUsername(candidate) {
     }
     return null;
 }
+/**
+ * Extract numeric LinkedIn ID from candidate.
+ * Checks multiple fields in order of preference:
+ * 1. numericLinkedInId / numeric_linkedin_id (direct numeric ID)
+ * 2. objectUrn / object_urn (URN format like "urn:li:member:307567")
+ * 3. linkedinId / linkedin_id (may contain URN or numeric ID)
+ */
+function extractNumericId(candidate) {
+    // Direct numeric ID field
+    const numericId = candidate.numericLinkedInId || candidate.numeric_linkedin_id;
+    if (numericId) {
+        const extracted = extractNumericLinkedInId(numericId);
+        if (extracted)
+            return extracted;
+    }
+    // objectUrn field (from Sales Navigator search results)
+    const objectUrn = candidate.objectUrn || candidate.object_urn;
+    if (objectUrn) {
+        const extracted = extractNumericLinkedInId(objectUrn);
+        if (extracted)
+            return extracted;
+    }
+    // linkedinId field (may contain URN or numeric ID)
+    const linkedinId = candidate.linkedinId || candidate.linkedin_id;
+    if (linkedinId) {
+        const extracted = extractNumericLinkedInId(linkedinId);
+        if (extracted)
+            return extracted;
+    }
+    return null;
+}
 /**
  * Create the LDD provider function
+ *
+ * Lookup priority:
+ * 1. Numeric LinkedIn ID (PREFERRED - stable, never changes)
+ * 2. Username (FALLBACK - can change over time)
  */
 function createLddProvider(config) {
     const { apiUrl, apiToken } = config;
@@ -74,36 +143,73 @@ function createLddProvider(config) {
         return noopProvider;
     }
     async function fetchEmail(candidate) {
+        // PRIORITY 1: Try numeric ID first (stable identifier)
+        const numericId = extractNumericId(candidate);
+        if (numericId) {
+            const result = await lookupByNumericId(numericId);
+            if (result)
+                return result;
+        }
+        // PRIORITY 2: Fall back to username (less reliable)
         const username = extractUsername(candidate);
-        if (!username) {
-            return null;
+        if (username) {
+            const result = await lookupByUsername(username);
+            if (result)
+                return result;
         }
+        return null;
+    }
+    async function lookupByNumericId(numericId) {
         try {
-            const endpoint = `${apiUrl}/api/v1/profiles/by-username/${encodeURIComponent(username)}`;
+            const endpoint = `${apiUrl}/api/v1/profiles/by-numeric-id/${encodeURIComponent(numericId)}`;
             const response = await requestWithRetry(endpoint, apiToken, 1, 100);
             if (!response.ok) {
                 return null;
             }
-            const data = (await response.json());
-            if (!data.success || !data.data) {
-                return null;
-            }
-            // Find first valid email
-            const emails = data.data.emails || [];
-            const validEmail = emails.find((e) => e.email_address && e.email_address.includes("@"));
-            if (!validEmail) {
+            return parseResponse(await response.json());
+        }
+        catch {
+            return null;
+        }
+    }
+    async function lookupByUsername(username) {
+        try {
+            const endpoint = `${apiUrl}/api/v1/profiles/by-username/${encodeURIComponent(username)}`;
+            const response = await requestWithRetry(endpoint, apiToken, 1, 100);
+            if (!response.ok) {
                 return null;
             }
-            return {
-                email: validEmail.email_address,
-                verified: true, // LDD data is pre-verified
-                score: 90, // High confidence from your own database
-            };
+            return parseResponse(await response.json());
         }
         catch {
             return null;
         }
     }
+    function parseResponse(data) {
+        if (!data.success || !data.data) {
+            return null;
+        }
+        // Return ALL valid emails from the profile
+        const profileEmails = data.data.emails || [];
+        const validEmails = profileEmails.filter((e) => e.email_address && e.email_address.includes("@"));
+        if (validEmails.length === 0) {
+            return null;
+        }
+        // Build multi-result with all emails
+        const emails = validEmails.map((e) => ({
+            email: e.email_address,
+            verified: true, // LDD data is pre-verified
+            confidence: 90, // High confidence from your own database
+            metadata: {
+                emailType: e.email_type,
+                fullName: data.data.full_name,
+                linkedinUsername: data.data.linkedin_username,
+                linkedinUrl: data.data.linkedin_profile_url,
+                numericLinkedInId: data.data.linkedin_id,
+            },
+        }));
+        return { emails };
+    }
     // Mark provider name for orchestrator
     fetchEmail.__name = "ldd";
     return fetchEmail;

package/dist/enrichment/providers/smartprospect.d.ts

@@ -7,8 +7,41 @@
  * 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
+ */
+import type { EnrichmentCandidate, ProviderResult, ProviderMultiResult, SmartProspectConfig, SmartProspectSearchFilters, SmartProspectSearchResponse, SmartProspectFetchResponse, SmartProspectContact, SmartProspectLocationResponse } from "../types";
+/**
+ * SmartProspect Location lookup options
  */
-import type { EnrichmentCandidate, ProviderResult, SmartProspectConfig } from "../types";
+export interface SmartProspectLocationOptions {
+    search?: string;
+    limit?: number;
+    offset?: number;
+}
+/**
+ * SmartProspect Client interface for direct API access
+ */
+export interface SmartProspectClient {
+    /** Search for contacts (FREE - no credits used) */
+    search: (filters: SmartProspectSearchFilters) => Promise<SmartProspectSearchResponse>;
+    /** Fetch/enrich emails for specific contact IDs (COSTS CREDITS) */
+    fetch: (contactIds: string[]) => Promise<SmartProspectFetchResponse>;
+    /** Search and immediately fetch all results (COSTS CREDITS for fetched contacts) */
+    searchAndFetch: (filters: SmartProspectSearchFilters) => Promise<{
+        searchResponse: SmartProspectSearchResponse;
+        fetchResponse: SmartProspectFetchResponse | null;
+        contacts: SmartProspectContact[];
+    }>;
+    /** Lookup countries (for typeahead) */
+    getCountries: (options?: SmartProspectLocationOptions) => Promise<SmartProspectLocationResponse>;
+    /** Lookup states (for typeahead) */
+    getStates: (options?: SmartProspectLocationOptions) => Promise<SmartProspectLocationResponse>;
+    /** Lookup cities (for typeahead) */
+    getCities: (options?: SmartProspectLocationOptions) => Promise<SmartProspectLocationResponse>;
+}
 /**
  * Create the SmartProspect provider function
  *
@@ -16,4 +49,33 @@ import type { EnrichmentCandidate, ProviderResult, SmartProspectConfig } from ".
  * 1. Direct token: Pass `apiToken` in config
  * 2. Credentials: Pass `email` and `password` in config for auto-login
  */
-export declare function createSmartProspectProvider(config: SmartProspectConfig): (candidate: EnrichmentCandidate) => Promise<ProviderResult | null>;
+export declare function createSmartProspectProvider(config: SmartProspectConfig): (candidate: EnrichmentCandidate) => Promise<ProviderResult | ProviderMultiResult | null>;
+/**
+ * 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']);
+ * ```
+ */
+export declare function createSmartProspectClient(config: SmartProspectConfig): SmartProspectClient | null;