linkedin-secret-sauce 0.12.0 → 0.12.2

package/dist/enrichment/types.js

@@ -8,27 +8,33 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.SMARTPROSPECT_SUB_INDUSTRIES = exports.PROVIDER_COSTS = exports.DEFAULT_PROVIDER_ORDER = void 0;
 /**
- * Default provider order - 2-Phase Strategy
+ * Default provider order - 3-Phase Strategy
  *
  * PHASE 1 - Free lookups (run in parallel):
  *   - ldd: LinkedIn Data Dump - real verified emails (FREE with subscription)
  *   - smartprospect: SmartLead API - real verified emails (FREE with subscription)
+ *   - cosiall: Cosiall Profile Emails - emails from LinkedIn profiles (FREE)
+ *   - trykitt: TryKitt.ai - AI email finder (FREE for individuals, unlimited)
+ *
+ * PHASE 2 - Pattern guessing + verification (if Phase 1 < 80% confidence):
  *   - construct: Pattern guessing + MX check (FREE)
+ *   - bounceban: BounceBan catch-all verification (FREE single, $0.003/bulk)
  *
- * PHASE 2 - Paid verification/finding (only if Phase 1 inconclusive):
- *   - bouncer: SMTP verify constructed emails ($0.006/email)
- *   - snovio: Email finder for catch-all domains ($0.02/email)
- *   - hunter: Hunter.io fallback ($0.005/email)
+ * PHASE 3 - Paid finders (only if Phase 2 inconclusive):
+ *   - hunter: Hunter.io email finder ($0.005/email)
+ *   - snovio: Snov.io email finder ($0.02/email)
  *
- * Note: dropcontact available but not in default order (expensive at $0.01)
+ * Note: bouncer, dropcontact available but not in default order
  */
 exports.DEFAULT_PROVIDER_ORDER = [
     "ldd",
     "smartprospect",
+    "cosiall",
+    "trykitt",
     "construct",
-    "bouncer",
-    "snovio",
+    "bounceban",
     "hunter",
+    "snovio",
 ];
 /**
  * Provider costs in USD per lookup
@@ -36,7 +42,10 @@ exports.DEFAULT_PROVIDER_ORDER = [
  * Costs based on 2025 pricing:
  * - ldd: FREE (subscription-based)
  * - smartprospect: FREE (included in SmartLead subscription)
+ * - cosiall: FREE (uses global Cosiall config)
+ * - trykitt: FREE (unlimited for individuals, $0.005/email high volume)
  * - construct: FREE (pattern guessing + MX check)
+ * - bounceban: FREE single / $0.003/email bulk (catch-all specialist)
  * - bouncer: $0.006/email (SMTP verification, 99%+ accuracy)
  * - snovio: $0.02/email (email finding + verification)
  * - hunter: $0.005/email
@@ -46,6 +55,9 @@ exports.PROVIDER_COSTS = {
     construct: 0,
     ldd: 0,
     smartprospect: 0,
+    cosiall: 0,
+    trykitt: 0, // FREE for individuals
+    bounceban: 0.003, // FREE single, $0.003 bulk
     hunter: 0.005,
     dropcontact: 0.01,
     bouncer: 0.006,
@@ -57,46 +69,46 @@ exports.PROVIDER_COSTS = {
  */
 exports.SMARTPROSPECT_SUB_INDUSTRIES = [
     // Software & Internet
-    'Internet',
-    'Information Technology and Services',
-    'Information Services',
-    'Computer Software',
-    'Computer & Network Security',
-    'Computer Games',
+    "Internet",
+    "Information Technology and Services",
+    "Information Services",
+    "Computer Software",
+    "Computer & Network Security",
+    "Computer Games",
     // Real Estate & Construction
-    'Glass, Ceramics & Concrete',
-    'Construction',
-    'Commercial Real Estate',
-    'Civil Engineering',
-    'Building Materials',
-    'Architecture & Planning',
+    "Glass, Ceramics & Concrete",
+    "Construction",
+    "Commercial Real Estate",
+    "Civil Engineering",
+    "Building Materials",
+    "Architecture & Planning",
     // Business Services
-    'Writing and Editing',
-    'Translation and Localization',
-    'Think Tanks',
-    'Staffing and Recruiting',
-    'Security and Investigations',
-    'Public Safety',
-    'Public Relations and Communications',
-    'Program Development',
-    'Professional Training & Coaching',
-    'Market Research',
-    'Marketing and Advertising',
-    'Management Consulting',
-    'Legal Services',
-    'Law Practice',
-    'Law Enforcement',
-    'International Trade and Development',
-    'Import and Export',
-    'Human Resources',
-    'Graphic Design',
-    'Facilities Services',
-    'Executive Office',
-    'Events Services',
-    'Environmental Services',
-    'Design',
-    'Business Supplies and Equipment',
-    'Animation',
-    'Alternative Dispute Resolution',
-    'Outsourcing/Offshoring',
+    "Writing and Editing",
+    "Translation and Localization",
+    "Think Tanks",
+    "Staffing and Recruiting",
+    "Security and Investigations",
+    "Public Safety",
+    "Public Relations and Communications",
+    "Program Development",
+    "Professional Training & Coaching",
+    "Market Research",
+    "Marketing and Advertising",
+    "Management Consulting",
+    "Legal Services",
+    "Law Practice",
+    "Law Enforcement",
+    "International Trade and Development",
+    "Import and Export",
+    "Human Resources",
+    "Graphic Design",
+    "Facilities Services",
+    "Executive Office",
+    "Events Services",
+    "Environmental Services",
+    "Design",
+    "Business Supplies and Equipment",
+    "Animation",
+    "Alternative Dispute Resolution",
+    "Outsourcing/Offshoring",
 ];

package/dist/enrichment/utils/candidate-parser.d.ts

@@ -0,0 +1,107 @@
+/**
+ * Shared Candidate Parsing Utilities
+ *
+ * Extracts common fields from EnrichmentCandidate objects.
+ * Reduces code duplication across providers by centralizing field extraction logic.
+ */
+import type { EnrichmentCandidate } from "../types";
+/**
+ * Parsed name components from a candidate
+ */
+export interface ParsedName {
+    firstName: string;
+    lastName: string;
+    fullName: string;
+}
+/**
+ * Parsed company/domain info from a candidate
+ */
+export interface ParsedCompany {
+    company: string | null;
+    domain: string | null;
+}
+/**
+ * Parsed LinkedIn identifiers from a candidate
+ */
+export interface ParsedLinkedIn {
+    /** LinkedIn username/handle (e.g., "john-doe") */
+    username: string | null;
+    /** LinkedIn profile URL */
+    url: string | null;
+    /** Numeric LinkedIn ID (stable, never changes) */
+    numericId: string | null;
+}
+/**
+ * Full parsed candidate with all extracted fields
+ */
+export interface ParsedCandidate {
+    name: ParsedName;
+    company: ParsedCompany;
+    linkedin: ParsedLinkedIn;
+    title: string | null;
+}
+/**
+ * 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)
+ */
+export declare function extractName(candidate: EnrichmentCandidate): ParsedName;
+/**
+ * Extract company and domain from a candidate
+ *
+ * Checks multiple field naming conventions:
+ * - company, currentCompany, organization, org
+ * - domain, companyDomain, company_domain
+ */
+export declare function extractCompany(candidate: EnrichmentCandidate): ParsedCompany;
+/**
+ * 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
+ */
+export declare function extractLinkedInUsernameFromUrl(url: string | undefined | null): string | 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,...)"
+ */
+export declare function extractNumericLinkedInId(input: string | undefined | null): string | 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.
+ */
+export declare function extractLinkedIn(candidate: EnrichmentCandidate): ParsedLinkedIn;
+/**
+ * Extract job title from a candidate
+ */
+export declare function extractTitle(candidate: EnrichmentCandidate): string | 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.
+ */
+export declare function parseCandidate(candidate: EnrichmentCandidate): ParsedCandidate;
+/**
+ * Build a LinkedIn URL from a username/handle
+ */
+export declare function buildLinkedInUrl(username: string): string;
+/**
+ * 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
+ */
+export declare function hasMinimumFields(candidate: EnrichmentCandidate, requireDomain?: boolean): boolean;

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;