linkedin-secret-sauce 0.12.1 → 0.12.3

package/dist/enrichment/utils/candidate-parser.js

@@ -0,0 +1,173 @@
+"use strict";
+/**
+ * Shared Candidate Parsing Utilities
+ *
+ * Extracts common fields from EnrichmentCandidate objects.
+ * Reduces code duplication across providers by centralizing field extraction logic.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.extractName = extractName;
+exports.extractCompany = extractCompany;
+exports.extractLinkedInUsernameFromUrl = extractLinkedInUsernameFromUrl;
+exports.extractNumericLinkedInId = extractNumericLinkedInId;
+exports.extractLinkedIn = extractLinkedIn;
+exports.extractTitle = extractTitle;
+exports.parseCandidate = parseCandidate;
+exports.buildLinkedInUrl = buildLinkedInUrl;
+exports.hasMinimumFields = hasMinimumFields;
+/**
+ * Extract name components from a candidate
+ *
+ * Checks multiple field naming conventions:
+ * - firstName, first_name, first
+ * - lastName, last_name, last
+ * - name, fullName, full_name (split on space)
+ */
+function extractName(candidate) {
+    const rawName = candidate.name || candidate.fullName || candidate.full_name;
+    const firstName = candidate.firstName ||
+        candidate.first_name ||
+        candidate.first ||
+        rawName?.split(" ")?.[0] ||
+        "";
+    const lastName = candidate.lastName ||
+        candidate.last_name ||
+        candidate.last ||
+        rawName?.split(" ")?.slice(1).join(" ") ||
+        "";
+    const fullName = rawName || (firstName && lastName ? `${firstName} ${lastName}`.trim() : firstName);
+    return { firstName, lastName, fullName };
+}
+/**
+ * Extract company and domain from a candidate
+ *
+ * Checks multiple field naming conventions:
+ * - company, currentCompany, organization, org
+ * - domain, companyDomain, company_domain
+ */
+function extractCompany(candidate) {
+    const company = candidate.company ||
+        candidate.currentCompany ||
+        candidate.organization ||
+        candidate.org ||
+        null;
+    const domain = candidate.domain ||
+        candidate.companyDomain ||
+        candidate.company_domain ||
+        null;
+    return { company, domain };
+}
+/**
+ * Extract LinkedIn username from a URL
+ *
+ * Handles various URL formats:
+ * - https://linkedin.com/in/john-doe
+ * - https://www.linkedin.com/in/john-doe/
+ * - linkedin.com/in/john-doe?param=value
+ */
+function extractLinkedInUsernameFromUrl(url) {
+    if (!url)
+        return null;
+    const match = url.match(/linkedin\.com\/in\/([^\/\?]+)/i);
+    return match ? match[1] : null;
+}
+/**
+ * Extract numeric LinkedIn ID from various formats
+ *
+ * Handles:
+ * - Direct numeric ID: "307567"
+ * - URN format: "urn:li:member:307567"
+ * - Sales profile URN: "urn:li:fs_salesProfile:(307567,...)"
+ */
+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 identifiers from a candidate
+ *
+ * Returns username, URL, and numeric ID (if available).
+ * Numeric ID is preferred for lookups as it never changes.
+ */
+function extractLinkedIn(candidate) {
+    // Extract URL
+    const url = candidate.linkedinUrl || candidate.linkedin_url || null;
+    // Extract username - try direct field first, then extract from URL
+    const username = candidate.linkedinUsername ||
+        candidate.linkedin_username ||
+        candidate.linkedinHandle ||
+        candidate.linkedin_handle ||
+        extractLinkedInUsernameFromUrl(url);
+    // Extract numeric ID - check multiple fields in order of preference
+    const numericId = extractNumericLinkedInId(candidate.numericLinkedInId) ||
+        extractNumericLinkedInId(candidate.numeric_linkedin_id) ||
+        extractNumericLinkedInId(candidate.objectUrn) ||
+        extractNumericLinkedInId(candidate.object_urn) ||
+        extractNumericLinkedInId(candidate.linkedinId) ||
+        extractNumericLinkedInId(candidate.linkedin_id);
+    return { username, url, numericId };
+}
+/**
+ * Extract job title from a candidate
+ */
+function extractTitle(candidate) {
+    return (candidate.title ||
+        candidate.currentRole ||
+        candidate.current_role ||
+        null);
+}
+/**
+ * Parse all common fields from a candidate
+ *
+ * Use this for a complete extraction of all fields at once.
+ * For partial extraction, use the individual functions.
+ */
+function parseCandidate(candidate) {
+    return {
+        name: extractName(candidate),
+        company: extractCompany(candidate),
+        linkedin: extractLinkedIn(candidate),
+        title: extractTitle(candidate),
+    };
+}
+/**
+ * Build a LinkedIn URL from a username/handle
+ */
+function buildLinkedInUrl(username) {
+    return `https://www.linkedin.com/in/${username}`;
+}
+/**
+ * Check if a candidate has minimum required fields for email lookup
+ *
+ * @param candidate - The candidate to check
+ * @param requireDomain - Whether domain is required (default: true)
+ * @returns true if candidate has at least name and optionally domain
+ */
+function hasMinimumFields(candidate, requireDomain = true) {
+    const { name, company } = parseCandidate(candidate);
+    // Must have at least first name
+    if (!name.firstName) {
+        return false;
+    }
+    // Domain required for most providers
+    if (requireDomain && !company.domain) {
+        return false;
+    }
+    return true;
+}

package/dist/enrichment/utils/noop-provider.d.ts

@@ -0,0 +1,39 @@
+/**
+ * No-Op Provider Factory
+ *
+ * Creates a no-op (no operation) provider function that returns null.
+ * Used when a provider is not configured (missing API key, etc.)
+ *
+ * This reduces code duplication across providers that need to return
+ * a disabled/unconfigured provider.
+ */
+import type { ProviderResult, ProviderName } from "../types";
+/**
+ * Provider function type with optional name property
+ */
+type NoOpProviderFunc = {
+    (): Promise<ProviderResult | null>;
+    __name?: string;
+};
+/**
+ * Create a no-op provider function with the specified name
+ *
+ * The returned function:
+ * - Always returns null (no email found)
+ * - Has a `__name` property for identification in the orchestrator
+ *
+ * @param name - The provider name for identification
+ * @returns A no-op provider function
+ *
+ * @example
+ * ```typescript
+ * export function createHunterProvider(config: HunterConfig) {
+ *   if (!config.apiKey) {
+ *     return createNoOpProvider("hunter");
+ *   }
+ *   // ... actual implementation
+ * }
+ * ```
+ */
+export declare function createNoOpProvider(name: ProviderName): NoOpProviderFunc;
+export {};

package/dist/enrichment/utils/noop-provider.js

@@ -0,0 +1,37 @@
+"use strict";
+/**
+ * No-Op Provider Factory
+ *
+ * Creates a no-op (no operation) provider function that returns null.
+ * Used when a provider is not configured (missing API key, etc.)
+ *
+ * This reduces code duplication across providers that need to return
+ * a disabled/unconfigured provider.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createNoOpProvider = createNoOpProvider;
+/**
+ * Create a no-op provider function with the specified name
+ *
+ * The returned function:
+ * - Always returns null (no email found)
+ * - Has a `__name` property for identification in the orchestrator
+ *
+ * @param name - The provider name for identification
+ * @returns A no-op provider function
+ *
+ * @example
+ * ```typescript
+ * export function createHunterProvider(config: HunterConfig) {
+ *   if (!config.apiKey) {
+ *     return createNoOpProvider("hunter");
+ *   }
+ *   // ... actual implementation
+ * }
+ * ```
+ */
+function createNoOpProvider(name) {
+    const noopProvider = async () => null;
+    noopProvider.__name = name;
+    return noopProvider;
+}

package/dist/enrichment/utils/rate-limiter.d.ts

@@ -0,0 +1,103 @@
+/**
+ * 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.
+ */
+import type { ProviderName } from "../types";
+/**
+ * Rate limit configuration for a provider
+ */
+export interface RateLimitConfig {
+    /** Maximum requests per window */
+    maxRequests: number;
+    /** Window size in milliseconds */
+    windowMs: number;
+    /** Optional minimum delay between requests in milliseconds */
+    minDelayMs?: number;
+}
+/**
+ * Rate limit status for a provider
+ */
+export interface RateLimitStatus {
+    /** Whether the provider is currently rate limited */
+    isLimited: boolean;
+    /** Number of requests in current window */
+    requestsInWindow: number;
+    /** Maximum allowed requests */
+    maxRequests: number;
+    /** Time until rate limit resets (ms) */
+    resetInMs: number;
+    /** Recommended delay before next request (ms) */
+    recommendedDelayMs: number;
+}
+/**
+ * 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
+ */
+export declare const DEFAULT_RATE_LIMITS: Partial<Record<ProviderName, RateLimitConfig>>;
+/**
+ * Rate limiter instance for tracking provider requests
+ */
+export declare class RateLimiter {
+    private requests;
+    private configs;
+    private lastRequestTime;
+    constructor(customConfigs?: Partial<Record<ProviderName, RateLimitConfig>>);
+    /**
+     * Record a request for a provider
+     */
+    recordRequest(provider: ProviderName): void;
+    /**
+     * Check if a provider is rate limited
+     */
+    isRateLimited(provider: ProviderName): boolean;
+    /**
+     * Get rate limit status for a provider
+     */
+    getStatus(provider: ProviderName): RateLimitStatus;
+    /**
+     * Wait until rate limit allows a request
+     *
+     * @returns Promise that resolves when it's safe to make a request
+     */
+    waitForSlot(provider: ProviderName): Promise<void>;
+    /**
+     * Execute a function with rate limiting
+     *
+     * Automatically waits for rate limit slot and records the request.
+     */
+    execute<T>(provider: ProviderName, fn: () => Promise<T>): Promise<T>;
+    /**
+     * Get all provider statuses
+     */
+    getAllStatuses(): Map<ProviderName, RateLimitStatus>;
+    /**
+     * Reset rate limit tracking for a provider
+     */
+    reset(provider: ProviderName): void;
+    /**
+     * Reset all rate limit tracking
+     */
+    resetAll(): void;
+    /**
+     * Prune old records outside the window
+     */
+    private pruneRecords;
+}
+/**
+ * Get the global rate limiter instance
+ */
+export declare function getRateLimiter(): RateLimiter;
+/**
+ * Create a new rate limiter with custom configs
+ */
+export declare function createRateLimiter(configs?: Partial<Record<ProviderName, RateLimitConfig>>): RateLimiter;

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[];
+    }>;
+};