linkedin-secret-sauce 0.10.1 → 0.11.0

package/dist/enrichment/index.d.ts

@@ -39,7 +39,7 @@ export { isPersonalEmail, isBusinessEmail, isPersonalDomain, PERSONAL_DOMAINS, }
 export { isDisposableEmail, isDisposableDomain, DISPOSABLE_DOMAINS, } from "./utils/disposable-domains";
 export { isValidEmailSyntax, isRoleAccount, asciiFold, cleanNamePart, hostnameFromUrl, extractLinkedInUsername, } from "./utils/validation";
 export { verifyEmailMx } from "./verification/mx";
-export { createConstructProvider, createLddProvider, createSmartProspectProvider, createHunterProvider, createApolloProvider, createDropcontactProvider, } from "./providers";
+export { createConstructProvider, createLddProvider, createSmartProspectProvider, createHunterProvider, createApolloProvider, createDropcontactProvider, createBouncerProvider, createSnovioProvider, verifyEmailWithBouncer, checkCatchAllDomain, verifyEmailsBatch, findEmailsWithSnovio, verifyEmailWithSnovio, clearSnovioTokenCache, } from "./providers";
 export { extractNumericLinkedInId } from "./providers/ldd";
 export { createSmartProspectClient, type SmartProspectClient, type SmartProspectLocationOptions, } from "./providers/smartprospect";
 export { enrichBusinessEmail, enrichBatch, enrichAllEmails, enrichAllBatch } from "./orchestrator";

package/dist/enrichment/index.js

@@ -42,7 +42,8 @@ var __exportStar = (this && this.__exportStar) || function(m, exports) {
     for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.salesLeadToContact = exports.getEmailsForLinkedInContactsBatch = exports.getEmailsForLinkedInContact = exports.createLinkedInEnricher = exports.enrichLinkedInContactsBatch = exports.enrichLinkedInContact = exports.parseLinkedInSearchResponse = exports.buildSmartProspectFiltersFromLinkedIn = exports.matchContacts = exports.findBestMatch = exports.classifyMatchQuality = exports.calculateMatchConfidence = exports.clearFileCache = exports.isFileCacheEnabled = exports.disableFileCache = exports.enableFileCache = exports.getSmartLeadTokenCacheStats = exports.clearAllSmartLeadTokens = exports.clearSmartLeadToken = exports.getSmartLeadUser = exports.getSmartLeadToken = exports.enrichAllBatch = exports.enrichAllEmails = exports.enrichBatch = exports.enrichBusinessEmail = exports.createSmartProspectClient = exports.extractNumericLinkedInId = exports.createDropcontactProvider = exports.createApolloProvider = exports.createHunterProvider = exports.createSmartProspectProvider = exports.createLddProvider = exports.createConstructProvider = exports.verifyEmailMx = exports.extractLinkedInUsername = exports.hostnameFromUrl = exports.cleanNamePart = exports.asciiFold = exports.isRoleAccount = exports.isValidEmailSyntax = exports.DISPOSABLE_DOMAINS = exports.isDisposableDomain = exports.isDisposableEmail = exports.PERSONAL_DOMAINS = exports.isPersonalDomain = exports.isBusinessEmail = exports.isPersonalEmail = void 0;
+exports.enrichLinkedInContact = exports.parseLinkedInSearchResponse = exports.buildSmartProspectFiltersFromLinkedIn = exports.matchContacts = exports.findBestMatch = exports.classifyMatchQuality = exports.calculateMatchConfidence = exports.clearFileCache = exports.isFileCacheEnabled = exports.disableFileCache = exports.enableFileCache = exports.getSmartLeadTokenCacheStats = exports.clearAllSmartLeadTokens = exports.clearSmartLeadToken = exports.getSmartLeadUser = exports.getSmartLeadToken = exports.enrichAllBatch = exports.enrichAllEmails = exports.enrichBatch = exports.enrichBusinessEmail = exports.createSmartProspectClient = exports.extractNumericLinkedInId = exports.clearSnovioTokenCache = exports.verifyEmailWithSnovio = exports.findEmailsWithSnovio = exports.verifyEmailsBatch = exports.checkCatchAllDomain = exports.verifyEmailWithBouncer = exports.createSnovioProvider = exports.createBouncerProvider = exports.createDropcontactProvider = exports.createApolloProvider = exports.createHunterProvider = exports.createSmartProspectProvider = exports.createLddProvider = exports.createConstructProvider = exports.verifyEmailMx = exports.extractLinkedInUsername = exports.hostnameFromUrl = exports.cleanNamePart = exports.asciiFold = exports.isRoleAccount = exports.isValidEmailSyntax = exports.DISPOSABLE_DOMAINS = exports.isDisposableDomain = exports.isDisposableEmail = exports.PERSONAL_DOMAINS = exports.isPersonalDomain = exports.isBusinessEmail = exports.isPersonalEmail = void 0;
+exports.salesLeadToContact = exports.getEmailsForLinkedInContactsBatch = exports.getEmailsForLinkedInContact = exports.createLinkedInEnricher = exports.enrichLinkedInContactsBatch = void 0;
 exports.createEnrichmentClient = createEnrichmentClient;
 const orchestrator_1 = require("./orchestrator");
 const construct_1 = require("./providers/construct");
@@ -51,13 +52,27 @@ const smartprospect_1 = require("./providers/smartprospect");
 const hunter_1 = require("./providers/hunter");
 const apollo_1 = require("./providers/apollo");
 const dropcontact_1 = require("./providers/dropcontact");
+const bouncer_1 = require("./providers/bouncer");
+const snovio_1 = require("./providers/snovio");
 /**
  * Default provider order
+ *
+ * Strategy:
+ * 1. construct - FREE pattern guessing with MX check
+ * 2. bouncer - SMTP verification of construct results ($0.006/email)
+ * 3. ldd - FREE LinkedIn data dump lookup
+ * 4. smartprospect - Paid SmartLead lookup ($0.01/email)
+ * 5. snovio - Email finder for catch-all domains ($0.02/email)
+ * 6. hunter - Hunter.io API ($0.005/email)
+ * 7. apollo - FREE Apollo.io lookup
+ * 8. dropcontact - Dropcontact API ($0.01/email)
  */
 const DEFAULT_ORDER = [
     "construct",
+    "bouncer",
     "ldd",
     "smartprospect",
+    "snovio",
     "hunter",
     "apollo",
     "dropcontact",
@@ -90,6 +105,12 @@ function createEnrichmentClient(config) {
     if (providerConfigs.dropcontact) {
         providerFuncs.set("dropcontact", (0, dropcontact_1.createDropcontactProvider)(providerConfigs.dropcontact));
     }
+    if (providerConfigs.bouncer) {
+        providerFuncs.set("bouncer", (0, bouncer_1.createBouncerProvider)(providerConfigs.bouncer));
+    }
+    if (providerConfigs.snovio) {
+        providerFuncs.set("snovio", (0, snovio_1.createSnovioProvider)(providerConfigs.snovio));
+    }
     // Build ordered provider list
     const providerOrder = options.providerOrder ?? DEFAULT_ORDER;
     const orderedProviders = [];
@@ -250,6 +271,16 @@ Object.defineProperty(exports, "createSmartProspectProvider", { enumerable: true
 Object.defineProperty(exports, "createHunterProvider", { enumerable: true, get: function () { return providers_1.createHunterProvider; } });
 Object.defineProperty(exports, "createApolloProvider", { enumerable: true, get: function () { return providers_1.createApolloProvider; } });
 Object.defineProperty(exports, "createDropcontactProvider", { enumerable: true, get: function () { return providers_1.createDropcontactProvider; } });
+Object.defineProperty(exports, "createBouncerProvider", { enumerable: true, get: function () { return providers_1.createBouncerProvider; } });
+Object.defineProperty(exports, "createSnovioProvider", { enumerable: true, get: function () { return providers_1.createSnovioProvider; } });
+// Bouncer utilities
+Object.defineProperty(exports, "verifyEmailWithBouncer", { enumerable: true, get: function () { return providers_1.verifyEmailWithBouncer; } });
+Object.defineProperty(exports, "checkCatchAllDomain", { enumerable: true, get: function () { return providers_1.checkCatchAllDomain; } });
+Object.defineProperty(exports, "verifyEmailsBatch", { enumerable: true, get: function () { return providers_1.verifyEmailsBatch; } });
+// Snov.io utilities
+Object.defineProperty(exports, "findEmailsWithSnovio", { enumerable: true, get: function () { return providers_1.findEmailsWithSnovio; } });
+Object.defineProperty(exports, "verifyEmailWithSnovio", { enumerable: true, get: function () { return providers_1.verifyEmailWithSnovio; } });
+Object.defineProperty(exports, "clearSnovioTokenCache", { enumerable: true, get: function () { return providers_1.clearSnovioTokenCache; } });
 // Re-export LDD utilities
 var ldd_2 = require("./providers/ldd");
 Object.defineProperty(exports, "extractNumericLinkedInId", { enumerable: true, get: function () { return ldd_2.extractNumericLinkedInId; } });

package/dist/enrichment/orchestrator.js

@@ -15,6 +15,13 @@ const disposable_domains_1 = require("./utils/disposable-domains");
 const validation_1 = require("./utils/validation");
 /**
  * Default provider costs in USD per lookup
+ *
+ * Costs based on 2025 pricing:
+ * - Bouncer: $0.006/email at scale (best accuracy 99%+)
+ * - Snov.io: $0.02/email (email finding + verification)
+ * - Hunter: $0.005/email
+ * - SmartProspect: $0.01/email
+ * - Dropcontact: $0.01/email
  */
 const _PROVIDER_COSTS = {
     construct: 0,
@@ -23,6 +30,8 @@ const _PROVIDER_COSTS = {
     hunter: 0.005,
     apollo: 0,
     dropcontact: 0.01,
+    bouncer: 0.006,
+    snovio: 0.02,
 };
 /**
  * Normalize provider result to canonical format

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

@@ -0,0 +1,67 @@
+/**
+ * Bouncer.io Email Verification Provider
+ *
+ * Provides SMTP-level email verification with 99%+ accuracy.
+ * Best for verifying pattern-guessed emails on non-catch-all domains.
+ *
+ * Features:
+ * - SMTP verification (checks if mailbox exists)
+ * - Catch-all domain detection
+ * - Disposable email detection
+ * - Role account detection
+ * - Toxicity scoring (0-5)
+ *
+ * @see https://docs.usebouncer.com
+ */
+import type { EnrichmentCandidate, ProviderResult, ProviderMultiResult, BouncerConfig, BouncerVerifyResponse } from '../types';
+/**
+ * Create the Bouncer verification provider
+ *
+ * NOTE: This provider is a VERIFIER, not a FINDER. It verifies emails
+ * that were generated by the construct provider or passed in the candidate.
+ *
+ * Usage in the enrichment flow:
+ * 1. construct provider generates email patterns
+ * 2. bouncer provider verifies which patterns are deliverable
+ * 3. Only verified emails are returned
+ */
+export declare function createBouncerProvider(config: BouncerConfig): (candidate: EnrichmentCandidate) => Promise<ProviderResult | ProviderMultiResult | null>;
+/**
+ * Standalone function to verify a single email via Bouncer
+ *
+ * Useful for ad-hoc verification outside the enrichment flow.
+ *
+ * @example
+ * ```typescript
+ * const result = await verifyEmailWithBouncer('test@example.com', {
+ *   apiKey: process.env.BOUNCER_API_KEY,
+ * });
+ * console.log(result.status); // 'deliverable' | 'undeliverable' | 'risky' | 'unknown'
+ * ```
+ */
+export declare function verifyEmailWithBouncer(email: string, config: BouncerConfig): Promise<BouncerVerifyResponse | null>;
+/**
+ * Check if a domain is catch-all via Bouncer
+ *
+ * Sends a verification request for a random email and checks acceptAll flag.
+ *
+ * @example
+ * ```typescript
+ * const isCatchAll = await checkCatchAllDomain('example.com', {
+ *   apiKey: process.env.BOUNCER_API_KEY,
+ * });
+ * ```
+ */
+export declare function checkCatchAllDomain(domain: string, config: BouncerConfig): Promise<boolean | null>;
+/**
+ * Verify multiple emails in batch via Bouncer
+ *
+ * @example
+ * ```typescript
+ * const results = await verifyEmailsBatch(
+ *   ['john@example.com', 'jane@example.com'],
+ *   { apiKey: process.env.BOUNCER_API_KEY }
+ * );
+ * ```
+ */
+export declare function verifyEmailsBatch(emails: string[], config: BouncerConfig): Promise<Map<string, BouncerVerifyResponse | null>>;

package/dist/enrichment/providers/bouncer.js

@@ -0,0 +1,233 @@
+"use strict";
+/**
+ * Bouncer.io Email Verification Provider
+ *
+ * Provides SMTP-level email verification with 99%+ accuracy.
+ * Best for verifying pattern-guessed emails on non-catch-all domains.
+ *
+ * Features:
+ * - SMTP verification (checks if mailbox exists)
+ * - Catch-all domain detection
+ * - Disposable email detection
+ * - Role account detection
+ * - Toxicity scoring (0-5)
+ *
+ * @see https://docs.usebouncer.com
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createBouncerProvider = createBouncerProvider;
+exports.verifyEmailWithBouncer = verifyEmailWithBouncer;
+exports.checkCatchAllDomain = checkCatchAllDomain;
+exports.verifyEmailsBatch = verifyEmailsBatch;
+const DEFAULT_API_URL = 'https://api.usebouncer.com/v1.1';
+const DEFAULT_TIMEOUT_MS = 30000;
+/**
+ * Map Bouncer status to confidence score
+ */
+function statusToConfidence(status, response) {
+    switch (status) {
+        case 'deliverable':
+            // High confidence - email verified as deliverable
+            // Reduce slightly if catch-all or high toxicity
+            let score = 95;
+            if (response.acceptAll)
+                score -= 20; // Catch-all reduces confidence
+            if (response.toxicity && response.toxicity >= 3)
+                score -= 10;
+            if (response.role)
+                score -= 5; // Role accounts slightly lower
+            return Math.max(50, score);
+        case 'risky':
+            // Medium confidence - risky but might work
+            return response.acceptAll ? 40 : 50;
+        case 'undeliverable':
+            // Email does not exist
+            return 0;
+        case 'unknown':
+            // Could not verify
+            return 30;
+        default:
+            return 0;
+    }
+}
+/**
+ * Extract email candidates from the enrichment candidate
+ * Bouncer is a VERIFICATION provider, so it needs emails to verify
+ */
+function extractEmailsToVerify(candidate) {
+    const emails = [];
+    // Check if candidate has pre-generated email patterns in metadata
+    const metadata = candidate._emailCandidates;
+    if (Array.isArray(metadata)) {
+        emails.push(...metadata.filter((e) => typeof e === 'string'));
+    }
+    return emails;
+}
+/**
+ * Verify a single email via Bouncer API
+ */
+async function verifyEmail(email, apiKey, apiUrl, timeoutMs) {
+    const controller = new AbortController();
+    const timeoutId = setTimeout(() => controller.abort(), timeoutMs);
+    try {
+        const url = `${apiUrl}/email/verify?email=${encodeURIComponent(email)}`;
+        const response = await fetch(url, {
+            method: 'GET',
+            headers: {
+                'x-api-key': apiKey,
+                'Accept': 'application/json',
+            },
+            signal: controller.signal,
+        });
+        if (!response.ok) {
+            // All HTTP errors return null - let caller decide how to handle
+            return null;
+        }
+        const data = await response.json();
+        return data;
+    }
+    catch {
+        // All errors (network, timeout, etc.) return null
+        return null;
+    }
+    finally {
+        clearTimeout(timeoutId);
+    }
+}
+/**
+ * Create the Bouncer verification provider
+ *
+ * NOTE: This provider is a VERIFIER, not a FINDER. It verifies emails
+ * that were generated by the construct provider or passed in the candidate.
+ *
+ * Usage in the enrichment flow:
+ * 1. construct provider generates email patterns
+ * 2. bouncer provider verifies which patterns are deliverable
+ * 3. Only verified emails are returned
+ */
+function createBouncerProvider(config) {
+    const { apiKey, apiUrl = DEFAULT_API_URL, timeoutMs = DEFAULT_TIMEOUT_MS } = config;
+    if (!apiKey) {
+        // Return no-op provider if not configured
+        const noop = async () => null;
+        noop.__name = 'bouncer';
+        return noop;
+    }
+    async function verifyEmails(candidate) {
+        const emailsToVerify = extractEmailsToVerify(candidate);
+        // If no emails to verify, return null
+        // The orchestrator will need to pass emails from construct
+        if (emailsToVerify.length === 0) {
+            return null;
+        }
+        const verifiedEmails = [];
+        // Verify each email candidate
+        for (const email of emailsToVerify) {
+            try {
+                const result = await verifyEmail(email, apiKey, apiUrl, timeoutMs);
+                if (result) {
+                    const confidence = statusToConfidence(result.status, result);
+                    // Only include emails that are potentially deliverable
+                    if (result.status === 'deliverable' || result.status === 'risky') {
+                        verifiedEmails.push({
+                            email: result.email,
+                            verified: result.status === 'deliverable',
+                            confidence,
+                            isCatchAll: result.acceptAll,
+                            metadata: {
+                                bouncerStatus: result.status,
+                                bouncerReason: result.reason,
+                                toxicity: result.toxicity,
+                                isDisposable: result.disposable,
+                                isRole: result.role,
+                                isFreeProvider: result.free,
+                            },
+                        });
+                    }
+                }
+            }
+            catch {
+                // Continue with other emails on error
+                continue;
+            }
+        }
+        if (verifiedEmails.length === 0) {
+            return null;
+        }
+        // Sort by confidence
+        verifiedEmails.sort((a, b) => (b.confidence ?? 0) - (a.confidence ?? 0));
+        return { emails: verifiedEmails };
+    }
+    // Mark provider name for orchestrator
+    verifyEmails.__name = 'bouncer';
+    return verifyEmails;
+}
+/**
+ * Standalone function to verify a single email via Bouncer
+ *
+ * Useful for ad-hoc verification outside the enrichment flow.
+ *
+ * @example
+ * ```typescript
+ * const result = await verifyEmailWithBouncer('test@example.com', {
+ *   apiKey: process.env.BOUNCER_API_KEY,
+ * });
+ * console.log(result.status); // 'deliverable' | 'undeliverable' | 'risky' | 'unknown'
+ * ```
+ */
+async function verifyEmailWithBouncer(email, config) {
+    const { apiKey, apiUrl = DEFAULT_API_URL, timeoutMs = DEFAULT_TIMEOUT_MS } = config;
+    return verifyEmail(email, apiKey, apiUrl, timeoutMs);
+}
+/**
+ * Check if a domain is catch-all via Bouncer
+ *
+ * Sends a verification request for a random email and checks acceptAll flag.
+ *
+ * @example
+ * ```typescript
+ * const isCatchAll = await checkCatchAllDomain('example.com', {
+ *   apiKey: process.env.BOUNCER_API_KEY,
+ * });
+ * ```
+ */
+async function checkCatchAllDomain(domain, config) {
+    const { apiKey, apiUrl = DEFAULT_API_URL, timeoutMs = DEFAULT_TIMEOUT_MS } = config;
+    // Generate a random email that almost certainly doesn't exist
+    const randomLocal = `bounce-test-${Date.now()}-${Math.random().toString(36).slice(2, 10)}`;
+    const testEmail = `${randomLocal}@${domain}`;
+    const result = await verifyEmail(testEmail, apiKey, apiUrl, timeoutMs);
+    if (!result) {
+        return null; // Could not determine
+    }
+    // If acceptAll is true, the domain accepts all emails (catch-all)
+    return result.acceptAll;
+}
+/**
+ * Verify multiple emails in batch via Bouncer
+ *
+ * @example
+ * ```typescript
+ * const results = await verifyEmailsBatch(
+ *   ['john@example.com', 'jane@example.com'],
+ *   { apiKey: process.env.BOUNCER_API_KEY }
+ * );
+ * ```
+ */
+async function verifyEmailsBatch(emails, config) {
+    const { apiKey, apiUrl = DEFAULT_API_URL, timeoutMs = DEFAULT_TIMEOUT_MS } = config;
+    const results = new Map();
+    // Verify in parallel with concurrency limit
+    const CONCURRENCY = 5;
+    for (let i = 0; i < emails.length; i += CONCURRENCY) {
+        const batch = emails.slice(i, i + CONCURRENCY);
+        const batchResults = await Promise.all(batch.map(async (email) => {
+            const result = await verifyEmail(email, apiKey, apiUrl, timeoutMs);
+            return { email, result };
+        }));
+        for (const { email, result } of batchResults) {
+            results.set(email, result);
+        }
+    }
+    return results;
+}

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

@@ -7,3 +7,5 @@ export { createSmartProspectProvider } from './smartprospect';
 export { createHunterProvider } from './hunter';
 export { createApolloProvider } from './apollo';
 export { createDropcontactProvider } from './dropcontact';
+export { createBouncerProvider, verifyEmailWithBouncer, checkCatchAllDomain, verifyEmailsBatch } from './bouncer';
+export { createSnovioProvider, findEmailsWithSnovio, verifyEmailWithSnovio, clearSnovioTokenCache } from './snovio';

package/dist/enrichment/providers/index.js

@@ -3,7 +3,7 @@
  * Email Enrichment Providers
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.createDropcontactProvider = exports.createApolloProvider = exports.createHunterProvider = exports.createSmartProspectProvider = exports.createLddProvider = exports.createConstructProvider = void 0;
+exports.clearSnovioTokenCache = exports.verifyEmailWithSnovio = exports.findEmailsWithSnovio = exports.createSnovioProvider = exports.verifyEmailsBatch = exports.checkCatchAllDomain = exports.verifyEmailWithBouncer = exports.createBouncerProvider = exports.createDropcontactProvider = exports.createApolloProvider = exports.createHunterProvider = exports.createSmartProspectProvider = exports.createLddProvider = exports.createConstructProvider = void 0;
 var construct_1 = require("./construct");
 Object.defineProperty(exports, "createConstructProvider", { enumerable: true, get: function () { return construct_1.createConstructProvider; } });
 var ldd_1 = require("./ldd");
@@ -16,3 +16,13 @@ var apollo_1 = require("./apollo");
 Object.defineProperty(exports, "createApolloProvider", { enumerable: true, get: function () { return apollo_1.createApolloProvider; } });
 var dropcontact_1 = require("./dropcontact");
 Object.defineProperty(exports, "createDropcontactProvider", { enumerable: true, get: function () { return dropcontact_1.createDropcontactProvider; } });
+var bouncer_1 = require("./bouncer");
+Object.defineProperty(exports, "createBouncerProvider", { enumerable: true, get: function () { return bouncer_1.createBouncerProvider; } });
+Object.defineProperty(exports, "verifyEmailWithBouncer", { enumerable: true, get: function () { return bouncer_1.verifyEmailWithBouncer; } });
+Object.defineProperty(exports, "checkCatchAllDomain", { enumerable: true, get: function () { return bouncer_1.checkCatchAllDomain; } });
+Object.defineProperty(exports, "verifyEmailsBatch", { enumerable: true, get: function () { return bouncer_1.verifyEmailsBatch; } });
+var snovio_1 = require("./snovio");
+Object.defineProperty(exports, "createSnovioProvider", { enumerable: true, get: function () { return snovio_1.createSnovioProvider; } });
+Object.defineProperty(exports, "findEmailsWithSnovio", { enumerable: true, get: function () { return snovio_1.findEmailsWithSnovio; } });
+Object.defineProperty(exports, "verifyEmailWithSnovio", { enumerable: true, get: function () { return snovio_1.verifyEmailWithSnovio; } });
+Object.defineProperty(exports, "clearSnovioTokenCache", { enumerable: true, get: function () { return snovio_1.clearSnovioTokenCache; } });

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

@@ -166,6 +166,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)
  */
@@ -185,6 +288,10 @@ export interface ProvidersConfig {
     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
@@ -263,13 +370,30 @@ export interface EnrichmentClient {
 /**
  * Available provider names
  */
-export type ProviderName = "construct" | "ldd" | "smartprospect" | "hunter" | "apollo" | "dropcontact";
+export type ProviderName = "construct" | "ldd" | "smartprospect" | "hunter" | "apollo" | "dropcontact" | "bouncer" | "snovio";
 /**
  * Default provider order
+ *
+ * Strategy:
+ * 1. construct - FREE pattern guessing with MX check
+ * 2. bouncer - SMTP verification of construct results ($0.006/email)
+ * 3. ldd - FREE LinkedIn data dump lookup
+ * 4. smartprospect - Paid SmartLead lookup ($0.01/email)
+ * 5. snovio - Email finder for catch-all domains ($0.02/email)
+ * 6. hunter - Hunter.io API ($0.005/email)
+ * 7. apollo - FREE Apollo.io lookup
+ * 8. dropcontact - Dropcontact API ($0.01/email)
  */
 export declare const DEFAULT_PROVIDER_ORDER: ProviderName[];
 /**
  * Provider costs in USD per lookup
+ *
+ * Costs based on 2025 pricing:
+ * - Bouncer: $0.006/email at scale (best accuracy 99%+)
+ * - Snov.io: $0.02/email (email finding + verification)
+ * - Hunter: $0.005/email
+ * - SmartProspect: $0.01/email
+ * - Dropcontact: $0.01/email
  */
 export declare const PROVIDER_COSTS: Record<ProviderName, number>;
 /**

package/dist/enrichment/types.js

@@ -9,17 +9,36 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.SMARTPROSPECT_SUB_INDUSTRIES = exports.PROVIDER_COSTS = exports.DEFAULT_PROVIDER_ORDER = void 0;
 /**
  * Default provider order
+ *
+ * Strategy:
+ * 1. construct - FREE pattern guessing with MX check
+ * 2. bouncer - SMTP verification of construct results ($0.006/email)
+ * 3. ldd - FREE LinkedIn data dump lookup
+ * 4. smartprospect - Paid SmartLead lookup ($0.01/email)
+ * 5. snovio - Email finder for catch-all domains ($0.02/email)
+ * 6. hunter - Hunter.io API ($0.005/email)
+ * 7. apollo - FREE Apollo.io lookup
+ * 8. dropcontact - Dropcontact API ($0.01/email)
  */
 exports.DEFAULT_PROVIDER_ORDER = [
     "construct",
+    "bouncer",
     "ldd",
     "smartprospect",
+    "snovio",
     "hunter",
     "apollo",
     "dropcontact",
 ];
 /**
  * Provider costs in USD per lookup
+ *
+ * Costs based on 2025 pricing:
+ * - Bouncer: $0.006/email at scale (best accuracy 99%+)
+ * - Snov.io: $0.02/email (email finding + verification)
+ * - Hunter: $0.005/email
+ * - SmartProspect: $0.01/email
+ * - Dropcontact: $0.01/email
  */
 exports.PROVIDER_COSTS = {
     construct: 0,
@@ -28,6 +47,8 @@ exports.PROVIDER_COSTS = {
     hunter: 0.005,
     apollo: 0,
     dropcontact: 0.01,
+    bouncer: 0.006,
+    snovio: 0.02,
 };
 /**
  * SmartProspect Sub-Industry values (exact API values - partial list)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "linkedin-secret-sauce",
-  "version": "0.10.1",
+  "version": "0.11.0",
   "description": "Private LinkedIn Sales Navigator client with automatic cookie management",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -10,26 +10,6 @@
   "publishConfig": {
     "registry": "https://registry.npmjs.org/"
   },
-  "scripts": {
-    "dev:playground": "pnpm -C apps/playground dev",
-    "search": "node scripts/rg-fast.mjs",
-    "rg:fast": "node scripts/rg-fast.mjs",
-    "build": "tsc -p tsconfig.json",
-    "typecheck": "tsc --noEmit",
-    "typecheck:playground": "pnpm -C apps/playground typecheck",
-    "typecheck:all": "pnpm typecheck && pnpm typecheck:playground",
-    "lint": "eslint \"src/**/*.ts\" --max-warnings=0",
-    "lint:playground": "eslint \"apps/playground/src/**/*.{ts,tsx}\" \"apps/playground/server/**/*.ts\" --max-warnings=0",
-    "lint:all": "eslint \"src/**/*.ts\" \"apps/playground/src/**/*.{ts,tsx}\" \"apps/playground/server/**/*.ts\" --max-warnings=0",
-    "lint:fix": "eslint \"src/**/*.ts\" \"apps/playground/src/**/*.{ts,tsx}\" \"apps/playground/server/**/*.ts\" --fix",
-    "check": "pnpm typecheck:all && pnpm lint:all",
-    "dev": "tsc -w -p tsconfig.json",
-    "test": "vitest run",
-    "prepublishOnly": "npm run build",
-    "release:patch": "npm version patch && git push --follow-tags",
-    "release:minor": "npm version minor && git push --follow-tags",
-    "release:major": "npm version major && git push --follow-tags"
-  },
   "keywords": [
     "linkedin",
     "sales-navigator",
@@ -59,5 +39,24 @@
     "husky": "^9.0.11",
     "typescript": "^5.9.3",
     "vitest": "^1.6.0"
+  },
+  "scripts": {
+    "dev:playground": "pnpm -C apps/playground dev",
+    "search": "node scripts/rg-fast.mjs",
+    "rg:fast": "node scripts/rg-fast.mjs",
+    "build": "tsc -p tsconfig.json",
+    "typecheck": "tsc --noEmit",
+    "typecheck:playground": "pnpm -C apps/playground typecheck",
+    "typecheck:all": "pnpm typecheck && pnpm typecheck:playground",
+    "lint": "eslint \"src/**/*.ts\" --max-warnings=0",
+    "lint:playground": "eslint \"apps/playground/src/**/*.{ts,tsx}\" \"apps/playground/server/**/*.ts\" --max-warnings=0",
+    "lint:all": "eslint \"src/**/*.ts\" \"apps/playground/src/**/*.{ts,tsx}\" \"apps/playground/server/**/*.ts\" --max-warnings=0",
+    "lint:fix": "eslint \"src/**/*.ts\" \"apps/playground/src/**/*.{ts,tsx}\" \"apps/playground/server/**/*.ts\" --fix",
+    "check": "pnpm typecheck:all && pnpm lint:all",
+    "dev": "tsc -w -p tsconfig.json",
+    "test": "vitest run",
+    "release:patch": "npm version patch && git push --follow-tags",
+    "release:minor": "npm version minor && git push --follow-tags",
+    "release:major": "npm version major && git push --follow-tags"
   }
-}
+}