linkedin-secret-sauce 0.3.29 → 0.5.0

package/dist/enrichment/providers/smartprospect.js

@@ -0,0 +1,249 @@
+"use strict";
+/**
+ * SmartProspect/Smartlead Provider
+ *
+ * Smartlead's prospect database - a REVERSE-ENGINEERED private API.
+ * Two-phase process: search (free) then fetch (costs credits).
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createSmartProspectProvider = createSmartProspectProvider;
+const DEFAULT_API_URL = 'https://prospect-api.smartlead.ai/api/search-email-leads';
+/**
+ * Delay helper for retry logic
+ */
+async function delay(ms) {
+    return new Promise((r) => setTimeout(r, ms));
+}
+/**
+ * HTTP request with retry on 429 rate limit
+ */
+async function requestWithRetry(url, options, retries = 2, backoffMs = 300) {
+    let lastErr;
+    for (let i = 0; i <= retries; i++) {
+        try {
+            const res = await fetch(url, options);
+            // Retry on rate limit
+            if (res.status === 429 && i < retries) {
+                await delay(backoffMs * Math.pow(2, i));
+                continue;
+            }
+            if (!res.ok) {
+                const errorText = await res.text().catch(() => '');
+                throw new Error(`SmartProspect API error: ${res.status} - ${errorText}`);
+            }
+            return (await res.json());
+        }
+        catch (err) {
+            lastErr = err;
+            if (i < retries) {
+                await delay(backoffMs * Math.pow(2, i));
+                continue;
+            }
+        }
+    }
+    throw lastErr ?? new Error('smartprospect_http_error');
+}
+/**
+ * Calculate match score between search input and contact result
+ */
+function calculateMatchScore(contact, searchName, company, title) {
+    let score = 0;
+    // Name match scoring (0-50 points)
+    const contactName = contact.fullName?.toLowerCase() || '';
+    const searchNameLower = searchName.toLowerCase();
+    if (contactName === searchNameLower) {
+        score += 50; // Exact match
+    }
+    else if (contactName.includes(searchNameLower) || searchNameLower.includes(contactName)) {
+        score += 30; // Partial match
+    }
+    // Company match scoring (0-30 points)
+    if (company) {
+        const contactCompany = contact.company?.name?.toLowerCase() || '';
+        const searchCompany = company.toLowerCase();
+        if (contactCompany === searchCompany) {
+            score += 30; // Exact match
+        }
+        else if (contactCompany.includes(searchCompany) || searchCompany.includes(contactCompany)) {
+            score += 15; // Partial match
+        }
+    }
+    // Title match scoring (0-10 points)
+    if (title) {
+        const contactTitle = contact.title?.toLowerCase() || '';
+        const searchTitle = title.toLowerCase();
+        if (contactTitle.includes(searchTitle) || searchTitle.includes(contactTitle)) {
+            score += 10;
+        }
+    }
+    // Deliverability score bonus (0-10 points)
+    if (contact.emailDeliverability > 0) {
+        score += contact.emailDeliverability * 10;
+    }
+    return score;
+}
+/**
+ * Extract name components from candidate
+ */
+function extractNames(candidate) {
+    const firstName = candidate.firstName ||
+        candidate.first_name ||
+        candidate.first ||
+        candidate.name?.split(' ')?.[0] ||
+        '';
+    const lastName = candidate.lastName ||
+        candidate.last_name ||
+        candidate.last ||
+        candidate.name?.split(' ')?.slice(1).join(' ') ||
+        '';
+    return { firstName, lastName };
+}
+/**
+ * Create the SmartProspect provider function
+ */
+function createSmartProspectProvider(config) {
+    const { apiToken, apiUrl = DEFAULT_API_URL } = config;
+    if (!apiToken) {
+        // Return a no-op provider if not configured
+        const noopProvider = async () => null;
+        noopProvider.__name = 'smartprospect';
+        return noopProvider;
+    }
+    /**
+     * Search for contacts matching filters (FREE - no credits used)
+     */
+    async function searchContacts(filters) {
+        try {
+            const response = await requestWithRetry(`${apiUrl}/search-contacts`, {
+                method: 'POST',
+                headers: {
+                    Authorization: `Bearer ${apiToken}`,
+                    'Content-Type': 'application/json',
+                    Accept: 'application/json',
+                },
+                body: JSON.stringify({
+                    ...filters,
+                    dontDisplayOwnedContact: filters.dontDisplayOwnedContact ?? true,
+                    limit: filters.limit ?? 10,
+                    titleExactMatch: filters.titleExactMatch ?? false,
+                }),
+            });
+            return response;
+        }
+        catch {
+            return {
+                success: false,
+                message: 'Search failed',
+                data: { list: [], total_count: 0 },
+            };
+        }
+    }
+    /**
+     * Fetch/enrich emails for specific contact IDs (COSTS CREDITS)
+     */
+    async function fetchContacts(contactIds) {
+        try {
+            const response = await requestWithRetry(`${apiUrl}/fetch-contacts`, {
+                method: 'POST',
+                headers: {
+                    Authorization: `Bearer ${apiToken}`,
+                    'Content-Type': 'application/json',
+                    Accept: 'application/json',
+                },
+                body: JSON.stringify({ contactIds }),
+            });
+            return response;
+        }
+        catch {
+            return {
+                success: false,
+                message: 'Fetch failed',
+                data: {
+                    list: [],
+                    total_count: 0,
+                    metrics: {
+                        totalContacts: 0,
+                        totalEmails: 0,
+                        noEmailFound: 0,
+                        invalidEmails: 0,
+                        catchAllEmails: 0,
+                        verifiedEmails: 0,
+                        completed: 0,
+                    },
+                    leads_found: 0,
+                    email_fetched: 0,
+                    verification_status_list: [],
+                },
+            };
+        }
+    }
+    async function fetchEmail(candidate) {
+        const { firstName, lastName } = extractNames(candidate);
+        if (!firstName) {
+            return null; // Minimum requirement
+        }
+        const fullName = `${firstName} ${lastName}`.trim();
+        const company = candidate.company || candidate.currentCompany || candidate.organization || undefined;
+        const title = candidate.title || candidate.currentRole || candidate.current_role || undefined;
+        const domain = candidate.domain || candidate.companyDomain || candidate.company_domain || undefined;
+        // Build search filters
+        const filters = {
+            name: [fullName],
+            limit: 5, // Get top 5 to find best match
+        };
+        if (company) {
+            filters.company = [company];
+        }
+        if (domain) {
+            filters.domain = [domain];
+        }
+        // Step 1: Search for contacts (FREE)
+        const searchResult = await searchContacts(filters);
+        if (!searchResult.success || searchResult.data.list.length === 0) {
+            return null;
+        }
+        // Find best match by scoring
+        const matches = searchResult.data.list;
+        let bestMatch = null;
+        let bestScore = 0;
+        for (const contact of matches) {
+            const score = calculateMatchScore(contact, fullName, company, title);
+            if (score > bestScore) {
+                bestScore = score;
+                bestMatch = contact;
+            }
+        }
+        if (!bestMatch) {
+            return null;
+        }
+        // Step 2: Fetch email for best match (COSTS CREDITS)
+        const fetchResult = await fetchContacts([bestMatch.id]);
+        if (!fetchResult.success || fetchResult.data.list.length === 0) {
+            return null;
+        }
+        const enrichedContact = fetchResult.data.list[0];
+        const email = enrichedContact?.email;
+        if (!email) {
+            return null;
+        }
+        // Calculate verification confidence
+        const isVerified = enrichedContact.verificationStatus === 'valid';
+        const isCatchAll = enrichedContact.verificationStatus === 'catch_all';
+        const deliverability = enrichedContact.emailDeliverability || 0;
+        let confidence = deliverability * 100;
+        if (isVerified) {
+            confidence = Math.max(confidence, 90);
+        }
+        else if (isCatchAll) {
+            confidence = Math.min(confidence, 75);
+        }
+        return {
+            email,
+            verified: isVerified || isCatchAll, // Accept catch-all as semi-verified
+            score: confidence,
+        };
+    }
+    // Mark provider name for orchestrator
+    fetchEmail.__name = 'smartprospect';
+    return fetchEmail;
+}

package/dist/enrichment/types.d.ts

@@ -0,0 +1,329 @@
+/**
+ * Email Enrichment Types
+ *
+ * Core types for the email enrichment module. These types are designed to be
+ * stateless - consumers pass their own API keys and configuration.
+ */
+/**
+ * Canonical email result returned by enrichment operations
+ */
+export interface CanonicalEmail {
+    /** The found business email, or null if not found */
+    business_email: string | null;
+    /** Which provider found the email */
+    business_email_source: string | null;
+    /** Whether the email was verified */
+    business_email_verified: boolean;
+    /** Confidence score (0-100) */
+    business_email_confidence?: number;
+    /** ISO timestamp of when the check was performed */
+    last_checked_at: string;
+    /** Status for debugging */
+    status?: string;
+}
+/**
+ * Raw result from a provider before normalization
+ */
+export interface ProviderResult {
+    email?: string | null;
+    verified?: boolean;
+    score?: number;
+    confidence?: number;
+}
+/**
+ * Provider function signature
+ */
+export type ProviderFunc = (candidate: EnrichmentCandidate) => Promise<ProviderResult | null>;
+/**
+ * Input candidate for enrichment - flexible to accept various naming conventions
+ */
+export interface EnrichmentCandidate {
+    firstName?: string;
+    first_name?: string;
+    first?: string;
+    lastName?: string;
+    last_name?: string;
+    last?: string;
+    name?: string;
+    fullName?: string;
+    full_name?: string;
+    company?: string;
+    currentCompany?: string;
+    organization?: string;
+    org?: string;
+    domain?: string;
+    companyDomain?: string;
+    company_domain?: string;
+    linkedinUsername?: string;
+    linkedin_username?: string;
+    linkedinUrl?: string;
+    linkedin_url?: string;
+    linkedinId?: string;
+    linkedin_id?: string;
+    title?: string;
+    currentRole?: string;
+    current_role?: string;
+}
+/**
+ * Hunter.io provider configuration
+ */
+export interface HunterConfig {
+    apiKey: string;
+}
+/**
+ * Apollo.io provider configuration
+ */
+export interface ApolloConfig {
+    apiKey: string;
+}
+/**
+ * SmartProspect/Smartlead provider configuration
+ */
+export interface SmartProspectConfig {
+    apiToken: string;
+    apiUrl?: string;
+}
+/**
+ * LinkedIn Data Dump provider configuration
+ */
+export interface LddConfig {
+    apiUrl: string;
+    apiToken: string;
+}
+/**
+ * Dropcontact provider configuration
+ */
+export interface DropcontactConfig {
+    apiKey: string;
+}
+/**
+ * Email construction provider configuration (no API key needed)
+ */
+export interface ConstructConfig {
+    /** Maximum email pattern attempts (default: 8) */
+    maxAttempts?: number;
+    /** Timeout for MX verification in ms (default: 5000) */
+    timeoutMs?: number;
+}
+/**
+ * All provider configurations
+ */
+export interface ProvidersConfig {
+    construct?: ConstructConfig;
+    ldd?: LddConfig;
+    smartprospect?: SmartProspectConfig;
+    hunter?: HunterConfig;
+    apollo?: ApolloConfig;
+    dropcontact?: DropcontactConfig;
+}
+/**
+ * Options for enrichment operations
+ */
+export interface EnrichmentOptions {
+    /** Maximum cost per email enrichment in USD (default: Infinity) */
+    maxCostPerEmail?: number;
+    /** Minimum confidence threshold 0-100 (default: 0) */
+    confidenceThreshold?: number;
+    /** Provider order (default: ['construct', 'ldd', 'smartprospect', 'hunter', 'apollo', 'dropcontact']) */
+    providerOrder?: ProviderName[];
+    /** Retry delay in ms on transient errors (default: 200) */
+    retryMs?: number;
+}
+/**
+ * Options for batch enrichment
+ */
+export interface BatchEnrichmentOptions extends EnrichmentOptions {
+    /** Batch size for parallel processing (default: 50) */
+    batchSize?: number;
+    /** Delay between batches in ms (default: 200) */
+    delayMs?: number;
+}
+/**
+ * Cache adapter interface - consumers provide their own caching implementation
+ */
+export interface CacheAdapter {
+    /** Get cached result for an email */
+    get: (email: string) => Promise<CanonicalEmail | null>;
+    /** Set cached result for an email */
+    set: (email: string, result: CanonicalEmail, ttlMs?: number) => Promise<void>;
+}
+/**
+ * Cost callback - called when a provider incurs a cost
+ */
+export type CostCallback = (provider: string, costUsd: number) => void | Promise<void>;
+/**
+ * Logger interface - consumers can provide their own logger
+ */
+export interface EnrichmentLogger {
+    debug?: (message: string, context?: Record<string, unknown>) => void;
+    info?: (message: string, context?: Record<string, unknown>) => void;
+    warn?: (message: string, context?: Record<string, unknown>) => void;
+    error?: (message: string, context?: Record<string, unknown>) => void;
+}
+/**
+ * Configuration for createEnrichmentClient
+ */
+export interface EnrichmentClientConfig {
+    /** Provider API keys and configuration */
+    providers: ProvidersConfig;
+    /** Enrichment options */
+    options?: EnrichmentOptions;
+    /** Optional cache adapter */
+    cache?: CacheAdapter;
+    /** Optional cost tracking callback */
+    onCost?: CostCallback;
+    /** Optional logger */
+    logger?: EnrichmentLogger;
+}
+/**
+ * Enrichment client interface
+ */
+export interface EnrichmentClient {
+    /** Enrich a single candidate */
+    enrich: (candidate: EnrichmentCandidate) => Promise<CanonicalEmail>;
+    /** Enrich multiple candidates in batches */
+    enrichBatch: (candidates: EnrichmentCandidate[], options?: BatchEnrichmentOptions) => Promise<Array<{
+        candidate: EnrichmentCandidate;
+    } & CanonicalEmail>>;
+}
+/**
+ * Available provider names
+ */
+export type ProviderName = 'construct' | 'ldd' | 'smartprospect' | 'hunter' | 'apollo' | 'dropcontact';
+/**
+ * Default provider order
+ */
+export declare const DEFAULT_PROVIDER_ORDER: ProviderName[];
+/**
+ * Provider costs in USD per lookup
+ */
+export declare const PROVIDER_COSTS: Record<ProviderName, number>;
+/**
+ * Email verification result
+ */
+export interface VerificationResult {
+    /** Whether the email is valid */
+    valid: boolean | null;
+    /** Confidence score 0-100 */
+    confidence: number;
+    /** Reason for the result */
+    reason?: 'valid' | 'invalid' | 'syntax' | 'mx_missing' | 'disposable' | 'role_account' | 'catch_all' | 'timeout' | 'error';
+    /** Whether this is a catch-all domain */
+    isCatchAll: boolean;
+    /** Whether this is a role account (info@, support@, etc.) */
+    isRoleAccount: boolean;
+    /** Whether this is a disposable email */
+    isDisposable: boolean;
+    /** MX records found */
+    mxRecords?: string[];
+}
+export interface SmartProspectCompany {
+    name: string;
+    website: string;
+}
+export interface SmartProspectContact {
+    id: string;
+    firstName: string;
+    lastName: string;
+    fullName: string;
+    title: string;
+    company: SmartProspectCompany;
+    department: string[];
+    level: string;
+    industry: string;
+    subIndustry: string;
+    companyHeadCount: string;
+    companyRevenue: string;
+    country: string;
+    state: string;
+    city: string;
+    email: string;
+    emailSource?: string;
+    linkedin: string;
+    emailDeliverability: number;
+    address: string;
+    status?: string;
+    verificationStatus?: string;
+    catchAllStatus?: string;
+}
+export interface SmartProspectSearchFilters {
+    name?: string[];
+    firstName?: string[];
+    lastName?: string[];
+    title?: string[];
+    company?: string[];
+    domain?: string[];
+    department?: string[];
+    level?: string[];
+    industry?: string[];
+    country?: string[];
+    state?: string[];
+    city?: string[];
+    companyHeadCount?: string[];
+    companyRevenue?: string[];
+    dontDisplayOwnedContact?: boolean;
+    limit?: number;
+    titleExactMatch?: boolean;
+    scroll_id?: string;
+}
+export interface SmartProspectSearchResponse {
+    success: boolean;
+    message: string;
+    data: {
+        list: SmartProspectContact[];
+        scroll_id?: string;
+        filter_id?: number;
+        total_count: number;
+    };
+}
+export interface SmartProspectFetchResponse {
+    success: boolean;
+    message: string;
+    data: {
+        list: SmartProspectContact[];
+        total_count: number;
+        metrics: {
+            totalContacts: number;
+            totalEmails: number;
+            noEmailFound: number;
+            invalidEmails: number;
+            catchAllEmails: number;
+            verifiedEmails: number;
+            completed: number;
+        };
+        leads_found: number;
+        email_fetched: number;
+        verification_status_list: string[];
+    };
+}
+export interface LddProfileEmail {
+    email_address: string;
+    email_type?: string | null;
+}
+export interface LddProfilePhone {
+    phone_number: string;
+    phone_type?: string | null;
+}
+export interface LddProfileData {
+    source_record_id: string;
+    linkedin_profile_url?: string | null;
+    linkedin_id?: string | null;
+    linkedin_username?: string | null;
+    first_name?: string | null;
+    last_name?: string | null;
+    full_name?: string | null;
+    profile_headline?: string | null;
+    profile_summary?: string | null;
+    profile_location?: string | null;
+    emails: LddProfileEmail[];
+    phones: LddProfilePhone[];
+}
+export type LddApiResponse = {
+    success: true;
+    data: LddProfileData;
+} | {
+    success: false;
+    error: string;
+    message: string;
+    statusCode?: number;
+};

package/dist/enrichment/types.js

@@ -0,0 +1,31 @@
+"use strict";
+/**
+ * Email Enrichment Types
+ *
+ * Core types for the email enrichment module. These types are designed to be
+ * stateless - consumers pass their own API keys and configuration.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PROVIDER_COSTS = exports.DEFAULT_PROVIDER_ORDER = void 0;
+/**
+ * Default provider order
+ */
+exports.DEFAULT_PROVIDER_ORDER = [
+    'construct',
+    'ldd',
+    'smartprospect',
+    'hunter',
+    'apollo',
+    'dropcontact',
+];
+/**
+ * Provider costs in USD per lookup
+ */
+exports.PROVIDER_COSTS = {
+    construct: 0,
+    ldd: 0,
+    smartprospect: 0.01,
+    hunter: 0.005,
+    apollo: 0,
+    dropcontact: 0.01,
+};

package/dist/enrichment/utils/disposable-domains.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Disposable Email Domain Detection
+ *
+ * Detects disposable/temporary email domains (Mailinator, Guerrillamail, etc.)
+ * that should be filtered out when enriching emails.
+ */
+/**
+ * Set of known disposable email domains (600+)
+ */
+export declare const DISPOSABLE_DOMAINS: Set<string>;
+/**
+ * Check if an email is from a disposable domain
+ *
+ * @param email - Email address to check
+ * @returns true if the email is from a disposable domain
+ */
+export declare function isDisposableEmail(email: string): boolean;
+/**
+ * Check if a domain is a disposable email domain
+ *
+ * @param domain - Domain to check
+ * @returns true if the domain is a disposable email domain
+ */
+export declare function isDisposableDomain(domain: string): boolean;