linkedin-secret-sauce 0.12.0 → 0.12.2

package/dist/enrichment/utils/rate-limiter.js

@@ -0,0 +1,204 @@
+"use strict";
+/**
+ * Rate Limiter for Email Enrichment Providers
+ *
+ * Tracks request rates per provider and enforces limits to avoid API throttling.
+ * Uses a sliding window approach to track requests.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.RateLimiter = exports.DEFAULT_RATE_LIMITS = void 0;
+exports.getRateLimiter = getRateLimiter;
+exports.createRateLimiter = createRateLimiter;
+/**
+ * Default rate limits per provider
+ *
+ * Based on documented API limits:
+ * - TryKitt: 2 req/sec, 120 req/min
+ * - Hunter: 10 req/sec
+ * - Snovio: 60 req/min
+ * - BounceBan: 10 req/sec
+ * - Bouncer: 10 req/sec
+ * - Dropcontact: 5 req/sec
+ * - SmartProspect: 2 req/sec
+ */
+exports.DEFAULT_RATE_LIMITS = {
+    trykitt: { maxRequests: 120, windowMs: 60000, minDelayMs: 500 },
+    hunter: { maxRequests: 10, windowMs: 1000, minDelayMs: 100 },
+    snovio: { maxRequests: 60, windowMs: 60000, minDelayMs: 1000 },
+    bounceban: { maxRequests: 10, windowMs: 1000, minDelayMs: 100 },
+    bouncer: { maxRequests: 10, windowMs: 1000, minDelayMs: 100 },
+    dropcontact: { maxRequests: 5, windowMs: 1000, minDelayMs: 200 },
+    smartprospect: { maxRequests: 2, windowMs: 1000, minDelayMs: 500 },
+    // Free providers have no external limits
+    construct: { maxRequests: 100, windowMs: 1000, minDelayMs: 0 },
+    ldd: { maxRequests: 100, windowMs: 1000, minDelayMs: 0 },
+    cosiall: { maxRequests: 10, windowMs: 1000, minDelayMs: 100 },
+};
+/**
+ * Rate limiter instance for tracking provider requests
+ */
+class RateLimiter {
+    requests = new Map();
+    configs = new Map();
+    lastRequestTime = new Map();
+    constructor(customConfigs) {
+        // Initialize with default configs
+        for (const [provider, config] of Object.entries(exports.DEFAULT_RATE_LIMITS)) {
+            this.configs.set(provider, config);
+        }
+        // Override with custom configs
+        if (customConfigs) {
+            for (const [provider, config] of Object.entries(customConfigs)) {
+                if (config) {
+                    this.configs.set(provider, config);
+                }
+            }
+        }
+    }
+    /**
+     * Record a request for a provider
+     */
+    recordRequest(provider) {
+        const now = Date.now();
+        const records = this.requests.get(provider) || [];
+        records.push({ timestamp: now });
+        this.requests.set(provider, records);
+        this.lastRequestTime.set(provider, now);
+        // Prune old records
+        this.pruneRecords(provider);
+    }
+    /**
+     * Check if a provider is rate limited
+     */
+    isRateLimited(provider) {
+        return this.getStatus(provider).isLimited;
+    }
+    /**
+     * Get rate limit status for a provider
+     */
+    getStatus(provider) {
+        const config = this.configs.get(provider);
+        if (!config) {
+            return {
+                isLimited: false,
+                requestsInWindow: 0,
+                maxRequests: Infinity,
+                resetInMs: 0,
+                recommendedDelayMs: 0,
+            };
+        }
+        this.pruneRecords(provider);
+        const records = this.requests.get(provider) || [];
+        const now = Date.now();
+        // Calculate requests in current window
+        const windowStart = now - config.windowMs;
+        const requestsInWindow = records.filter((r) => r.timestamp >= windowStart).length;
+        // Check if limited
+        const isLimited = requestsInWindow >= config.maxRequests;
+        // Calculate reset time
+        let resetInMs = 0;
+        if (isLimited && records.length > 0) {
+            const oldestInWindow = records.find((r) => r.timestamp >= windowStart);
+            if (oldestInWindow) {
+                resetInMs = oldestInWindow.timestamp + config.windowMs - now;
+            }
+        }
+        // Calculate recommended delay
+        let recommendedDelayMs = config.minDelayMs || 0;
+        if (isLimited) {
+            recommendedDelayMs = Math.max(recommendedDelayMs, resetInMs);
+        }
+        else {
+            // Check minimum delay since last request
+            const lastRequest = this.lastRequestTime.get(provider) || 0;
+            const timeSinceLastRequest = now - lastRequest;
+            if (timeSinceLastRequest < (config.minDelayMs || 0)) {
+                recommendedDelayMs = (config.minDelayMs || 0) - timeSinceLastRequest;
+            }
+        }
+        return {
+            isLimited,
+            requestsInWindow,
+            maxRequests: config.maxRequests,
+            resetInMs: Math.max(0, resetInMs),
+            recommendedDelayMs: Math.max(0, recommendedDelayMs),
+        };
+    }
+    /**
+     * Wait until rate limit allows a request
+     *
+     * @returns Promise that resolves when it's safe to make a request
+     */
+    async waitForSlot(provider) {
+        const status = this.getStatus(provider);
+        if (status.recommendedDelayMs > 0) {
+            await new Promise((resolve) => setTimeout(resolve, status.recommendedDelayMs));
+        }
+    }
+    /**
+     * Execute a function with rate limiting
+     *
+     * Automatically waits for rate limit slot and records the request.
+     */
+    async execute(provider, fn) {
+        await this.waitForSlot(provider);
+        this.recordRequest(provider);
+        return fn();
+    }
+    /**
+     * Get all provider statuses
+     */
+    getAllStatuses() {
+        const statuses = new Map();
+        for (const provider of this.configs.keys()) {
+            statuses.set(provider, this.getStatus(provider));
+        }
+        return statuses;
+    }
+    /**
+     * Reset rate limit tracking for a provider
+     */
+    reset(provider) {
+        this.requests.delete(provider);
+        this.lastRequestTime.delete(provider);
+    }
+    /**
+     * Reset all rate limit tracking
+     */
+    resetAll() {
+        this.requests.clear();
+        this.lastRequestTime.clear();
+    }
+    /**
+     * Prune old records outside the window
+     */
+    pruneRecords(provider) {
+        const config = this.configs.get(provider);
+        if (!config)
+            return;
+        const records = this.requests.get(provider);
+        if (!records)
+            return;
+        const windowStart = Date.now() - config.windowMs;
+        const pruned = records.filter((r) => r.timestamp >= windowStart);
+        this.requests.set(provider, pruned);
+    }
+}
+exports.RateLimiter = RateLimiter;
+// Global rate limiter instance
+let globalRateLimiter = null;
+/**
+ * Get the global rate limiter instance
+ */
+function getRateLimiter() {
+    if (!globalRateLimiter) {
+        globalRateLimiter = new RateLimiter();
+    }
+    return globalRateLimiter;
+}
+/**
+ * Create a new rate limiter with custom configs
+ */
+function createRateLimiter(configs) {
+    return new RateLimiter(configs);
+}

package/dist/enrichment/utils/validation.d.ts

@@ -1,8 +1,10 @@
 /**
- * Email Validation Utilities
+ * Email and Candidate Validation Utilities
  *
- * Provides email syntax validation and name parsing utilities.
+ * Provides email syntax validation, name parsing utilities,
+ * and EnrichmentCandidate validation.
  */
+import type { EnrichmentCandidate } from "../types";
 /**
  * Validate email syntax
  *
@@ -19,7 +21,7 @@ export declare function isValidEmailSyntax(email: string): boolean;
 export declare function isRoleAccount(email: string): boolean;
 /**
  * ASCII fold diacritics for name normalization
- * e.g., "Jos" -> "Jose", "Mller" -> "Muller"
+ * e.g., "José" -> "Jose", "Müller" -> "Muller"
  */
 export declare function asciiFold(s: string): string;
 /**
@@ -40,3 +42,73 @@ export declare function hostnameFromUrl(url?: string | null): string | null;
  * @returns username or null if not found
  */
 export declare function extractLinkedInUsername(url: string): string | null;
+/**
+ * Validation result for an EnrichmentCandidate
+ */
+export interface CandidateValidationResult {
+    /** Whether the candidate is valid */
+    valid: boolean;
+    /** Error messages if invalid */
+    errors: string[];
+    /** Warning messages (valid but may have issues) */
+    warnings: string[];
+}
+/**
+ * Validate a domain format
+ */
+export declare function isValidDomain(domain: string): boolean;
+/**
+ * Validate a LinkedIn URL format
+ */
+export declare function isValidLinkedInUrl(url: string): boolean;
+/**
+ * Validate an EnrichmentCandidate object
+ *
+ * Checks for:
+ * - At least one name field present
+ * - Valid domain format (if provided)
+ * - Valid LinkedIn URL format (if provided)
+ * - No completely empty candidate
+ *
+ * @param candidate - The candidate to validate
+ * @returns Validation result with errors and warnings
+ *
+ * @example
+ * ```typescript
+ * const result = validateCandidate({
+ *   firstName: "John",
+ *   lastName: "Doe",
+ *   domain: "example.com"
+ * });
+ *
+ * if (!result.valid) {
+ *   console.error("Invalid candidate:", result.errors);
+ * }
+ * ```
+ */
+export declare function validateCandidate(candidate: EnrichmentCandidate): CandidateValidationResult;
+/**
+ * Validate a batch of candidates
+ *
+ * @param candidates - Array of candidates to validate
+ * @returns Array of validation results with index
+ */
+export declare function validateCandidates(candidates: EnrichmentCandidate[]): Array<{
+    index: number;
+    candidate: EnrichmentCandidate;
+    result: CandidateValidationResult;
+}>;
+/**
+ * Filter valid candidates from a batch
+ *
+ * @param candidates - Array of candidates to filter
+ * @returns Object with valid candidates and rejected ones with reasons
+ */
+export declare function filterValidCandidates(candidates: EnrichmentCandidate[]): {
+    valid: EnrichmentCandidate[];
+    invalid: Array<{
+        index: number;
+        candidate: EnrichmentCandidate;
+        errors: string[];
+    }>;
+};

package/dist/enrichment/utils/validation.js

@@ -1,8 +1,9 @@
 "use strict";
 /**
- * Email Validation Utilities
+ * Email and Candidate Validation Utilities
  *
- * Provides email syntax validation and name parsing utilities.
+ * Provides email syntax validation, name parsing utilities,
+ * and EnrichmentCandidate validation.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.isValidEmailSyntax = isValidEmailSyntax;
@@ -11,6 +12,15 @@ exports.asciiFold = asciiFold;
 exports.cleanNamePart = cleanNamePart;
 exports.hostnameFromUrl = hostnameFromUrl;
 exports.extractLinkedInUsername = extractLinkedInUsername;
+exports.isValidDomain = isValidDomain;
+exports.isValidLinkedInUrl = isValidLinkedInUrl;
+exports.validateCandidate = validateCandidate;
+exports.validateCandidates = validateCandidates;
+exports.filterValidCandidates = filterValidCandidates;
+const candidate_parser_1 = require("./candidate-parser");
+// =============================================================================
+// Email Syntax Validation
+// =============================================================================
 /**
  * Validate email syntax
  *
@@ -18,17 +28,17 @@ exports.extractLinkedInUsername = extractLinkedInUsername;
  * @returns true if the email has valid syntax
  */
 function isValidEmailSyntax(email) {
-    if (!email || typeof email !== 'string')
+    if (!email || typeof email !== "string")
         return false;
-    if (email.includes(' '))
+    if (email.includes(" "))
         return false;
-    const parts = email.split('@');
+    const parts = email.split("@");
     if (parts.length !== 2)
         return false;
     const [local, domain] = parts;
     if (!local || !domain)
         return false;
-    if (!domain.includes('.'))
+    if (!domain.includes("."))
         return false;
     if (local.length > 64)
         return false;
@@ -79,13 +89,16 @@ function isRoleAccount(email) {
     const emailLower = email.toLowerCase();
     return ROLE_PATTERNS.some((pattern) => pattern.test(emailLower));
 }
+// =============================================================================
+// Name Utilities
+// =============================================================================
 /**
  * ASCII fold diacritics for name normalization
- * e.g., "Jos" -> "Jose", "Mller" -> "Muller"
+ * e.g., "José" -> "Jose", "Müller" -> "Muller"
  */
 function asciiFold(s) {
     try {
-        return s.normalize('NFD').replace(/\p{Diacritic}+/gu, '');
+        return s.normalize("NFD").replace(/\p{Diacritic}+/gu, "");
     }
     catch {
         return s;
@@ -95,9 +108,12 @@ function asciiFold(s) {
  * Clean name part: lowercase, remove diacritics, keep only a-z0-9
  */
 function cleanNamePart(s) {
-    const lower = asciiFold(String(s || '').toLowerCase());
-    return lower.replace(/[^a-z0-9]/g, '');
+    const lower = asciiFold(String(s || "").toLowerCase());
+    return lower.replace(/[^a-z0-9]/g, "");
 }
+// =============================================================================
+// URL Utilities
+// =============================================================================
 /**
  * Extract hostname from URL
  *
@@ -110,7 +126,7 @@ function hostnameFromUrl(url) {
     try {
         const u = new URL(url);
         const h = u.hostname.toLowerCase();
-        return h.startsWith('www.') ? h.slice(4) : h;
+        return h.startsWith("www.") ? h.slice(4) : h;
     }
     catch {
         return null;
@@ -128,3 +144,140 @@ function extractLinkedInUsername(url) {
     const match = url.match(/linkedin\.com\/in\/([^/?]+)/);
     return match ? match[1] : null;
 }
+/**
+ * Domain regex pattern
+ */
+const DOMAIN_REGEX = /^[a-zA-Z0-9]([a-zA-Z0-9-]{0,61}[a-zA-Z0-9])?(\.[a-zA-Z0-9]([a-zA-Z0-9-]{0,61}[a-zA-Z0-9])?)*\.[a-zA-Z]{2,}$/;
+/**
+ * LinkedIn URL pattern
+ */
+const LINKEDIN_URL_REGEX = /linkedin\.com\/in\/[a-zA-Z0-9_-]+/i;
+/**
+ * Validate a domain format
+ */
+function isValidDomain(domain) {
+    if (!domain || typeof domain !== "string") {
+        return false;
+    }
+    return DOMAIN_REGEX.test(domain.trim().toLowerCase());
+}
+/**
+ * Validate a LinkedIn URL format
+ */
+function isValidLinkedInUrl(url) {
+    if (!url || typeof url !== "string") {
+        return false;
+    }
+    return LINKEDIN_URL_REGEX.test(url);
+}
+/**
+ * Validate an EnrichmentCandidate object
+ *
+ * Checks for:
+ * - At least one name field present
+ * - Valid domain format (if provided)
+ * - Valid LinkedIn URL format (if provided)
+ * - No completely empty candidate
+ *
+ * @param candidate - The candidate to validate
+ * @returns Validation result with errors and warnings
+ *
+ * @example
+ * ```typescript
+ * const result = validateCandidate({
+ *   firstName: "John",
+ *   lastName: "Doe",
+ *   domain: "example.com"
+ * });
+ *
+ * if (!result.valid) {
+ *   console.error("Invalid candidate:", result.errors);
+ * }
+ * ```
+ */
+function validateCandidate(candidate) {
+    const errors = [];
+    const warnings = [];
+    // Check if candidate is an object
+    if (!candidate || typeof candidate !== "object") {
+        return {
+            valid: false,
+            errors: ["Candidate must be a non-null object"],
+            warnings: [],
+        };
+    }
+    // Parse the candidate to get normalized fields
+    const parsed = (0, candidate_parser_1.parseCandidate)(candidate);
+    // Check for at least some identifying information
+    const hasName = !!parsed.name.firstName || !!parsed.name.lastName || !!parsed.name.fullName;
+    const hasLinkedIn = !!parsed.linkedin.username ||
+        !!parsed.linkedin.url ||
+        !!parsed.linkedin.numericId;
+    const hasDomain = !!parsed.company.domain;
+    const hasCompany = !!parsed.company.company;
+    if (!hasName && !hasLinkedIn) {
+        errors.push("Candidate must have at least a name or LinkedIn identifier");
+    }
+    // Validate domain format if provided
+    if (parsed.company.domain) {
+        // Remove common protocol prefixes that users might accidentally include
+        const cleanDomain = parsed.company.domain
+            .toLowerCase()
+            .replace(/^(https?:\/\/)?(www\.)?/, "");
+        if (!isValidDomain(cleanDomain)) {
+            errors.push(`Invalid domain format: "${parsed.company.domain}"`);
+        }
+    }
+    // Validate LinkedIn URL if provided
+    if (parsed.linkedin.url) {
+        if (!isValidLinkedInUrl(parsed.linkedin.url)) {
+            warnings.push(`LinkedIn URL may be invalid: "${parsed.linkedin.url}"`);
+        }
+    }
+    // Warn if name is very short (might be initial only)
+    if (parsed.name.firstName && parsed.name.firstName.length === 1) {
+        warnings.push("First name appears to be an initial - results may be less accurate");
+    }
+    // Warn if no domain/company for providers that need it
+    if (!hasDomain && !hasCompany && hasName && !hasLinkedIn) {
+        warnings.push("No domain or company provided - only LinkedIn-based providers will work");
+    }
+    return {
+        valid: errors.length === 0,
+        errors,
+        warnings,
+    };
+}
+/**
+ * Validate a batch of candidates
+ *
+ * @param candidates - Array of candidates to validate
+ * @returns Array of validation results with index
+ */
+function validateCandidates(candidates) {
+    return candidates.map((candidate, index) => ({
+        index,
+        candidate,
+        result: validateCandidate(candidate),
+    }));
+}
+/**
+ * Filter valid candidates from a batch
+ *
+ * @param candidates - Array of candidates to filter
+ * @returns Object with valid candidates and rejected ones with reasons
+ */
+function filterValidCandidates(candidates) {
+    const valid = [];
+    const invalid = [];
+    candidates.forEach((candidate, index) => {
+        const result = validateCandidate(candidate);
+        if (result.valid) {
+            valid.push(candidate);
+        }
+        else {
+            invalid.push({ index, candidate, errors: result.errors });
+        }
+    });
+    return { valid, invalid };
+}

package/dist/linkedin-api.d.ts

@@ -1,4 +1,4 @@
-import type { SalesSearchFilters, LinkedInProfile, SearchSalesResult, TypeaheadResult, SalesNavigatorProfile, Company } from "./types";
+import type { SalesSearchFilters, LinkedInProfile, SearchSalesResult, TypeaheadResult, SalesNavigatorProfile, SalesNavigatorProfileFull, Company } from "./types";
 /**
  * Fetches a LinkedIn profile by vanity URL (public identifier).
  * Results are cached for the configured TTL (default: 15 minutes).
@@ -128,3 +128,42 @@ export declare function getYearsInPositionOptions(): Promise<TypeaheadResult>;
  */
 export declare function getYearsOfExperienceOptions(): Promise<TypeaheadResult>;
 export declare function getSalesNavigatorProfileDetails(profileUrnOrId: string): Promise<SalesNavigatorProfile>;
+/**
+ * Fetches full Sales Navigator profile data including flagshipProfileUrl (LinkedIn handle).
+ * This is a more complete version that returns all available profile data.
+ *
+ * The key use case is extracting the LinkedIn handle from flagshipProfileUrl
+ * for use with email finder services like Hunter.io.
+ *
+ * @param profileUrnOrId - Profile identifier in any of these formats:
+ *   - Sales profile URN: "urn:li:fs_salesProfile:(ABC123xyz,NAME_SEARCH,abc)"
+ *   - FSD profile URN: "urn:li:fsd_profile:ABC123xyz"
+ *   - Bare key: "ABC123xyz"
+ * @returns Full Sales Navigator profile with flagshipProfileUrl, contactInfo, positions, etc.
+ * @throws LinkedInClientError with code NOT_FOUND if profile doesn't exist
+ *
+ * @example
+ * ```typescript
+ * const profile = await getSalesNavigatorProfileFull('urn:li:fs_salesProfile:(ABC123,NAME_SEARCH,xyz)');
+ * console.log(profile.flagshipProfileUrl); // "https://www.linkedin.com/in/john-doe"
+ *
+ * // Extract LinkedIn handle for Hunter.io
+ * const handle = extractLinkedInHandle(profile.flagshipProfileUrl);
+ * console.log(handle); // "john-doe"
+ * ```
+ */
+export declare function getSalesNavigatorProfileFull(profileUrnOrId: string): Promise<SalesNavigatorProfileFull>;
+/**
+ * Extracts LinkedIn handle/vanity from a flagship profile URL.
+ *
+ * @param flagshipProfileUrl - Full LinkedIn profile URL (e.g., "https://www.linkedin.com/in/john-doe")
+ * @returns LinkedIn handle/vanity (e.g., "john-doe") or null if not found
+ *
+ * @example
+ * ```typescript
+ * extractLinkedInHandle("https://www.linkedin.com/in/john-doe"); // "john-doe"
+ * extractLinkedInHandle("https://www.linkedin.com/in/georgi-metodiev-tech2rec"); // "georgi-metodiev-tech2rec"
+ * extractLinkedInHandle(null); // null
+ * ```
+ */
+export declare function extractLinkedInHandle(flagshipProfileUrl: string | null | undefined): string | null;