linkedin-secret-sauce 0.10.1 → 0.11.1

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

@@ -0,0 +1,58 @@
+/**
+ * Snov.io Email Finder Provider
+ *
+ * Provides email finding with 98% delivery rate and built-in verification.
+ * Best for finding emails when pattern guessing fails or on catch-all domains.
+ *
+ * Features:
+ * - Email finding by name + domain
+ * - Built-in email verification
+ * - Database of 70M+ contacts
+ * - LinkedIn profile support
+ *
+ * @see https://snov.io/api
+ */
+import type { EnrichmentCandidate, ProviderResult, ProviderMultiResult, SnovioConfig, SnovioGetEmailsResponse, SnovioVerificationStatus } from '../types';
+/**
+ * Create the Snov.io email finder provider
+ *
+ * This provider uses Snov.io's database to find verified emails
+ * when pattern guessing fails or for catch-all domains.
+ */
+export declare function createSnovioProvider(config: SnovioConfig): (candidate: EnrichmentCandidate) => Promise<ProviderResult | ProviderMultiResult | null>;
+/**
+ * Standalone function to find emails via Snov.io
+ *
+ * @example
+ * ```typescript
+ * const result = await findEmailsWithSnovio(
+ *   'John',
+ *   'Doe',
+ *   'example.com',
+ *   {
+ *     userId: process.env.SNOVIO_USER_ID,
+ *     apiSecret: process.env.SNOVIO_API_SECRET,
+ *   }
+ * );
+ * ```
+ */
+export declare function findEmailsWithSnovio(firstName: string, lastName: string, domain: string, config: SnovioConfig): Promise<SnovioGetEmailsResponse | null>;
+/**
+ * Verify a single email via Snov.io
+ *
+ * @example
+ * ```typescript
+ * const result = await verifyEmailWithSnovio('test@example.com', {
+ *   userId: process.env.SNOVIO_USER_ID,
+ *   apiSecret: process.env.SNOVIO_API_SECRET,
+ * });
+ * ```
+ */
+export declare function verifyEmailWithSnovio(email: string, config: SnovioConfig): Promise<{
+    email: string;
+    status: SnovioVerificationStatus;
+} | null>;
+/**
+ * Clear the cached access token (useful for testing)
+ */
+export declare function clearSnovioTokenCache(): void;

package/dist/enrichment/providers/snovio.js

@@ -0,0 +1,286 @@
+"use strict";
+/**
+ * Snov.io Email Finder Provider
+ *
+ * Provides email finding with 98% delivery rate and built-in verification.
+ * Best for finding emails when pattern guessing fails or on catch-all domains.
+ *
+ * Features:
+ * - Email finding by name + domain
+ * - Built-in email verification
+ * - Database of 70M+ contacts
+ * - LinkedIn profile support
+ *
+ * @see https://snov.io/api
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createSnovioProvider = createSnovioProvider;
+exports.findEmailsWithSnovio = findEmailsWithSnovio;
+exports.verifyEmailWithSnovio = verifyEmailWithSnovio;
+exports.clearSnovioTokenCache = clearSnovioTokenCache;
+const DEFAULT_API_URL = 'https://api.snov.io';
+const DEFAULT_TIMEOUT_MS = 30000;
+// Token cache
+let cachedAccessToken = null;
+let tokenExpiresAt = 0;
+/**
+ * Map Snov.io verification status to confidence score
+ */
+function statusToConfidence(status) {
+    switch (status) {
+        case 'valid':
+            return 95; // High confidence - verified email
+        case 'catch_all':
+            return 60; // Medium confidence - catch-all domain
+        case 'unverifiable':
+            return 40; // Low confidence - could not verify
+        case 'not_valid':
+            return 0; // Invalid email
+        case 'unknown':
+        default:
+            return 30;
+    }
+}
+/**
+ * Extract name and domain from candidate
+ */
+function extractNameAndDomain(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(' ') ||
+        '';
+    const domain = candidate.domain ||
+        candidate.companyDomain ||
+        candidate.company_domain ||
+        '';
+    if (!firstName || !domain) {
+        return null;
+    }
+    return { firstName, lastName, domain };
+}
+/**
+ * Get OAuth access token from Snov.io
+ */
+async function getAccessToken(userId, apiSecret, apiUrl, timeoutMs) {
+    // Return cached token if valid
+    if (cachedAccessToken && Date.now() < tokenExpiresAt) {
+        return cachedAccessToken;
+    }
+    const controller = new AbortController();
+    const timeoutId = setTimeout(() => controller.abort(), timeoutMs);
+    try {
+        const response = await fetch(`${apiUrl}/v1/oauth/access_token`, {
+            method: 'POST',
+            headers: {
+                'Content-Type': 'application/json',
+            },
+            body: JSON.stringify({
+                grant_type: 'client_credentials',
+                client_id: userId,
+                client_secret: apiSecret,
+            }),
+            signal: controller.signal,
+        });
+        if (!response.ok) {
+            return null;
+        }
+        const data = await response.json();
+        // Cache token with 5 minute buffer
+        cachedAccessToken = data.access_token;
+        tokenExpiresAt = Date.now() + (data.expires_in - 300) * 1000;
+        return data.access_token;
+    }
+    catch {
+        return null;
+    }
+    finally {
+        clearTimeout(timeoutId);
+    }
+}
+/**
+ * Find emails using Snov.io's get-emails-from-name API
+ */
+async function findEmailsByName(firstName, lastName, domain, accessToken, apiUrl, timeoutMs) {
+    const controller = new AbortController();
+    const timeoutId = setTimeout(() => controller.abort(), timeoutMs);
+    try {
+        const params = new URLSearchParams({
+            access_token: accessToken,
+            firstName,
+            lastName,
+            domain,
+        });
+        const response = await fetch(`${apiUrl}/v1/get-emails-from-names?${params}`, {
+            method: 'GET',
+            headers: {
+                'Accept': 'application/json',
+            },
+            signal: controller.signal,
+        });
+        if (!response.ok) {
+            // Handle rate limiting
+            if (response.status === 429) {
+                throw new Error('Rate limited by Snov.io API');
+            }
+            return null;
+        }
+        const data = await response.json();
+        return data;
+    }
+    catch (error) {
+        if (error instanceof Error && error.name === 'AbortError') {
+            return null; // Timeout
+        }
+        throw error;
+    }
+    finally {
+        clearTimeout(timeoutId);
+    }
+}
+/**
+ * Create the Snov.io email finder provider
+ *
+ * This provider uses Snov.io's database to find verified emails
+ * when pattern guessing fails or for catch-all domains.
+ */
+function createSnovioProvider(config) {
+    const { userId, apiSecret, apiUrl = DEFAULT_API_URL, timeoutMs = DEFAULT_TIMEOUT_MS, } = config;
+    if (!userId || !apiSecret) {
+        // Return no-op provider if not configured
+        const noop = async () => null;
+        noop.__name = 'snovio';
+        return noop;
+    }
+    async function findEmails(candidate) {
+        const nameAndDomain = extractNameAndDomain(candidate);
+        if (!nameAndDomain) {
+            return null;
+        }
+        const { firstName, lastName, domain } = nameAndDomain;
+        // Get access token
+        const accessToken = await getAccessToken(userId, apiSecret, apiUrl, timeoutMs);
+        if (!accessToken) {
+            return null;
+        }
+        // Find emails
+        const result = await findEmailsByName(firstName, lastName, domain, accessToken, apiUrl, timeoutMs);
+        if (!result || !result.success || !result.data?.emails?.length) {
+            return null;
+        }
+        // Convert to provider multi-result format
+        const emails = result.data.emails
+            .filter((e) => e.email && e.emailStatus !== 'not_valid')
+            .map((e) => ({
+            email: e.email,
+            verified: e.emailStatus === 'valid',
+            confidence: statusToConfidence(e.emailStatus),
+            isCatchAll: e.emailStatus === 'catch_all',
+            metadata: {
+                snovioStatus: e.emailStatus,
+                firstName: e.firstName,
+                lastName: e.lastName,
+                position: e.position,
+                companyName: e.companyName,
+                sourcePage: e.sourcePage,
+                type: e.type,
+            },
+        }));
+        if (emails.length === 0) {
+            return null;
+        }
+        // Sort by confidence
+        emails.sort((a, b) => (b.confidence ?? 0) - (a.confidence ?? 0));
+        return { emails };
+    }
+    // Mark provider name for orchestrator
+    findEmails.__name = 'snovio';
+    return findEmails;
+}
+/**
+ * Standalone function to find emails via Snov.io
+ *
+ * @example
+ * ```typescript
+ * const result = await findEmailsWithSnovio(
+ *   'John',
+ *   'Doe',
+ *   'example.com',
+ *   {
+ *     userId: process.env.SNOVIO_USER_ID,
+ *     apiSecret: process.env.SNOVIO_API_SECRET,
+ *   }
+ * );
+ * ```
+ */
+async function findEmailsWithSnovio(firstName, lastName, domain, config) {
+    const { userId, apiSecret, apiUrl = DEFAULT_API_URL, timeoutMs = DEFAULT_TIMEOUT_MS, } = config;
+    const accessToken = await getAccessToken(userId, apiSecret, apiUrl, timeoutMs);
+    if (!accessToken) {
+        return null;
+    }
+    return findEmailsByName(firstName, lastName, domain, accessToken, apiUrl, timeoutMs);
+}
+/**
+ * Verify a single email via Snov.io
+ *
+ * @example
+ * ```typescript
+ * const result = await verifyEmailWithSnovio('test@example.com', {
+ *   userId: process.env.SNOVIO_USER_ID,
+ *   apiSecret: process.env.SNOVIO_API_SECRET,
+ * });
+ * ```
+ */
+async function verifyEmailWithSnovio(email, config) {
+    const { userId, apiSecret, apiUrl = DEFAULT_API_URL, timeoutMs = DEFAULT_TIMEOUT_MS, } = config;
+    const accessToken = await getAccessToken(userId, apiSecret, apiUrl, timeoutMs);
+    if (!accessToken) {
+        return null;
+    }
+    const controller = new AbortController();
+    const timeoutId = setTimeout(() => controller.abort(), timeoutMs);
+    try {
+        const params = new URLSearchParams({
+            access_token: accessToken,
+            email,
+        });
+        const response = await fetch(`${apiUrl}/v1/email-verifier?${params}`, {
+            method: 'GET',
+            headers: {
+                'Accept': 'application/json',
+            },
+            signal: controller.signal,
+        });
+        if (!response.ok) {
+            return null;
+        }
+        const data = await response.json();
+        if (!data.success || !data.data?.emails?.length) {
+            return null;
+        }
+        const result = data.data.emails[0];
+        return {
+            email: result.email,
+            status: result.result,
+        };
+    }
+    catch {
+        return null;
+    }
+    finally {
+        clearTimeout(timeoutId);
+    }
+}
+/**
+ * Clear the cached access token (useful for testing)
+ */
+function clearSnovioTokenCache() {
+    cachedAccessToken = null;
+    tokenExpiresAt = 0;
+}

package/dist/enrichment/types.d.ts

@@ -126,12 +126,6 @@ export interface EnrichmentCandidate {
 export interface HunterConfig {
     apiKey: string;
 }
-/**
- * Apollo.io provider configuration
- */
-export interface ApolloConfig {
-    apiKey: string;
-}
 /**
  * SmartProspect/Smartlead provider configuration
  *
@@ -166,6 +160,109 @@ export interface LddConfig {
 export interface DropcontactConfig {
     apiKey: string;
 }
+/**
+ * Bouncer.io provider configuration
+ *
+ * Bouncer provides SMTP email verification with 99%+ accuracy.
+ * Best for verifying pattern-guessed emails on non-catch-all domains.
+ *
+ * @see https://docs.usebouncer.com
+ */
+export interface BouncerConfig {
+    /** Bouncer API key */
+    apiKey: string;
+    /** API URL override (default: https://api.usebouncer.com/v1.1) */
+    apiUrl?: string;
+    /** Timeout in ms (default: 30000) */
+    timeoutMs?: number;
+}
+/**
+ * Bouncer verification result status
+ */
+export type BouncerStatus = 'deliverable' | 'undeliverable' | 'risky' | 'unknown';
+/**
+ * Bouncer verification result reason
+ */
+export type BouncerReason = 'accepted_email' | 'rejected_email' | 'invalid_domain' | 'invalid_email' | 'unavailable_smtp' | 'dns_error' | 'low_deliverability' | 'low_quality' | 'catch_all' | 'full_mailbox' | 'role_account' | 'disposable' | 'timeout' | 'unknown';
+/**
+ * Bouncer API response for single email verification
+ */
+export interface BouncerVerifyResponse {
+    status: BouncerStatus;
+    reason: BouncerReason;
+    email: string;
+    domain: string;
+    account: string;
+    /** Whether this is a free email provider (Gmail, Yahoo, etc.) */
+    free: boolean;
+    /** Whether this is a disposable email */
+    disposable: boolean;
+    /** Whether this is a role-based email */
+    role: boolean;
+    /** Whether domain is catch-all (accepts all emails) */
+    acceptAll: boolean;
+    /** Did you mean suggestion for typos */
+    didYouMean?: string;
+    /** DNS information */
+    dns?: {
+        type: string;
+        record: string;
+    };
+    /** Toxicity score (0-5, higher = more risky) */
+    toxicity?: number;
+}
+/**
+ * Snov.io provider configuration
+ *
+ * Snov.io provides email finding with 98% delivery rate and built-in verification.
+ * Best for finding emails when pattern guessing fails or on catch-all domains.
+ *
+ * @see https://snov.io/api
+ */
+export interface SnovioConfig {
+    /** Snov.io API user ID */
+    userId: string;
+    /** Snov.io API secret */
+    apiSecret: string;
+    /** API URL override (default: https://api.snov.io) */
+    apiUrl?: string;
+    /** Timeout in ms (default: 30000) */
+    timeoutMs?: number;
+}
+/**
+ * Snov.io email verification status
+ */
+export type SnovioVerificationStatus = 'valid' | 'not_valid' | 'catch_all' | 'unverifiable' | 'unknown';
+/**
+ * Snov.io email result
+ */
+export interface SnovioEmailResult {
+    email: string;
+    emailStatus: SnovioVerificationStatus;
+    firstName?: string;
+    lastName?: string;
+    position?: string;
+    sourcePage?: string;
+    companyName?: string;
+    type?: 'prospect' | 'personal';
+    status?: string;
+}
+/**
+ * Snov.io get-emails-from-name API response
+ */
+export interface SnovioGetEmailsResponse {
+    success: boolean;
+    data: {
+        firstName: string;
+        lastName: string;
+        emails: SnovioEmailResult[];
+    };
+    params?: {
+        firstName: string;
+        lastName: string;
+        domain: string;
+    };
+}
 /**
  * Email construction provider configuration (no API key needed)
  */
@@ -174,6 +271,8 @@ export interface ConstructConfig {
     maxAttempts?: number;
     /** Timeout for MX verification in ms (default: 5000) */
     timeoutMs?: number;
+    /** Delay between SMTP verification checks in ms (default: 2000) */
+    smtpVerifyDelayMs?: number;
 }
 /**
  * All provider configurations
@@ -183,8 +282,11 @@ export interface ProvidersConfig {
     ldd?: LddConfig;
     smartprospect?: SmartProspectConfig;
     hunter?: HunterConfig;
-    apollo?: ApolloConfig;
     dropcontact?: DropcontactConfig;
+    /** Bouncer.io for SMTP email verification (99%+ accuracy) */
+    bouncer?: BouncerConfig;
+    /** Snov.io for email finding (98% delivery rate) */
+    snovio?: SnovioConfig;
 }
 /**
  * Options for enrichment operations
@@ -194,7 +296,7 @@ export interface EnrichmentOptions {
     maxCostPerEmail?: number;
     /** Minimum confidence threshold 0-100 (default: 0) */
     confidenceThreshold?: number;
-    /** Provider order (default: ['construct', 'ldd', 'smartprospect', 'hunter', 'apollo', 'dropcontact']) */
+    /** Provider order (default: ['ldd', 'smartprospect', 'construct', 'bouncer', 'snovio', 'hunter']) */
     providerOrder?: ProviderName[];
     /** Retry delay in ms on transient errors (default: 200) */
     retryMs?: number;
@@ -263,13 +365,34 @@ export interface EnrichmentClient {
 /**
  * Available provider names
  */
-export type ProviderName = "construct" | "ldd" | "smartprospect" | "hunter" | "apollo" | "dropcontact";
+export type ProviderName = "construct" | "ldd" | "smartprospect" | "hunter" | "dropcontact" | "bouncer" | "snovio";
 /**
- * Default provider order
+ * Default provider order - 2-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)
+ *   - construct: Pattern guessing + MX check (FREE)
+ *
+ * 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)
+ *
+ * Note: dropcontact available but not in default order (expensive at $0.01)
  */
 export declare const DEFAULT_PROVIDER_ORDER: ProviderName[];
 /**
  * Provider costs in USD per lookup
+ *
+ * Costs based on 2025 pricing:
+ * - ldd: FREE (subscription-based)
+ * - smartprospect: FREE (included in SmartLead subscription)
+ * - construct: FREE (pattern guessing + MX check)
+ * - bouncer: $0.006/email (SMTP verification, 99%+ accuracy)
+ * - snovio: $0.02/email (email finding + verification)
+ * - hunter: $0.005/email
+ * - dropcontact: $0.01/email (not in default order)
  */
 export declare const PROVIDER_COSTS: Record<ProviderName, number>;
 /**

package/dist/enrichment/types.js

@@ -8,26 +8,48 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.SMARTPROSPECT_SUB_INDUSTRIES = exports.PROVIDER_COSTS = exports.DEFAULT_PROVIDER_ORDER = void 0;
 /**
- * Default provider order
+ * Default provider order - 2-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)
+ *   - construct: Pattern guessing + MX check (FREE)
+ *
+ * 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)
+ *
+ * Note: dropcontact available but not in default order (expensive at $0.01)
  */
 exports.DEFAULT_PROVIDER_ORDER = [
-    "construct",
     "ldd",
     "smartprospect",
+    "construct",
+    "bouncer",
+    "snovio",
     "hunter",
-    "apollo",
-    "dropcontact",
 ];
 /**
  * Provider costs in USD per lookup
+ *
+ * Costs based on 2025 pricing:
+ * - ldd: FREE (subscription-based)
+ * - smartprospect: FREE (included in SmartLead subscription)
+ * - construct: FREE (pattern guessing + MX check)
+ * - bouncer: $0.006/email (SMTP verification, 99%+ accuracy)
+ * - snovio: $0.02/email (email finding + verification)
+ * - hunter: $0.005/email
+ * - dropcontact: $0.01/email (not in default order)
  */
 exports.PROVIDER_COSTS = {
     construct: 0,
     ldd: 0,
-    smartprospect: 0.01,
+    smartprospect: 0,
     hunter: 0.005,
-    apollo: 0,
     dropcontact: 0.01,
+    bouncer: 0.006,
+    snovio: 0.02,
 };
 /**
  * SmartProspect Sub-Industry values (exact API values - partial list)

package/dist/enrichment/utils/http-retry.d.ts

@@ -0,0 +1,96 @@
+/**
+ * HTTP Retry Utilities
+ *
+ * Shared utilities for HTTP requests with retry logic, rate limit handling,
+ * and exponential backoff. Used across all enrichment providers.
+ */
+/**
+ * Delay execution for specified milliseconds
+ */
+export declare function delay(ms: number): Promise<void>;
+/**
+ * Check if a value is truthy (not null, undefined, or empty string)
+ */
+export declare function truthy(v: unknown): boolean;
+/**
+ * Map common verification status strings to boolean
+ */
+export declare function mapVerifiedStatus(status: string | undefined | null): boolean | undefined;
+/**
+ * Options for fetch with retry
+ */
+export interface FetchWithRetryOptions {
+    /** Number of retries (default: 1) */
+    retries?: number;
+    /** Initial backoff in ms (default: 200) */
+    backoffMs?: number;
+    /** Timeout in ms (default: 30000) */
+    timeoutMs?: number;
+    /** HTTP status codes that should trigger retry (default: [429, 502, 503, 504]) */
+    retryOnStatus?: number[];
+}
+/**
+ * Generic API response type
+ */
+export interface ApiResponse {
+    data?: unknown;
+    result?: unknown;
+    people?: unknown[];
+    matches?: unknown[];
+    emails?: unknown[];
+    success?: boolean;
+    message?: string;
+    [key: string]: unknown;
+}
+/**
+ * HTTP request with retry on rate limit and transient errors
+ *
+ * Features:
+ * - Exponential backoff on rate limit (429)
+ * - Retry on server errors (502, 503, 504)
+ * - Configurable timeout
+ * - Returns typed response
+ *
+ * @example
+ * ```typescript
+ * const response = await fetchWithRetry<MyApiResponse>(
+ *   'https://api.example.com/data',
+ *   {
+ *     method: 'POST',
+ *     headers: { 'Content-Type': 'application/json' },
+ *     body: JSON.stringify({ query: 'test' }),
+ *   },
+ *   { retries: 2, backoffMs: 300 }
+ * );
+ * ```
+ */
+export declare function fetchWithRetry<T = ApiResponse>(url: string, init?: RequestInit, options?: FetchWithRetryOptions): Promise<T>;
+/**
+ * Simpler GET request with retry (no request body)
+ *
+ * @example
+ * ```typescript
+ * const data = await getWithRetry<UserData>(
+ *   `https://api.example.com/users/${id}`,
+ *   { 'Authorization': `Bearer ${token}` }
+ * );
+ * ```
+ */
+export declare function getWithRetry<T = ApiResponse>(url: string, headers?: Record<string, string>, options?: FetchWithRetryOptions): Promise<T>;
+/**
+ * POST request with JSON body and retry
+ *
+ * @example
+ * ```typescript
+ * const result = await postWithRetry<SearchResult>(
+ *   'https://api.example.com/search',
+ *   { query: 'test', limit: 10 },
+ *   { 'X-Api-Key': apiKey }
+ * );
+ * ```
+ */
+export declare function postWithRetry<T = ApiResponse>(url: string, body: Record<string, unknown>, headers?: Record<string, string>, options?: FetchWithRetryOptions): Promise<T>;
+/**
+ * Safe JSON parse with fallback
+ */
+export declare function safeJsonParse<T>(str: string, fallback: T): T;