linkedin-secret-sauce 0.12.1 → 0.12.3

package/dist/enrichment/providers/bounceban.js

@@ -0,0 +1,447 @@
+"use strict";
+/**
+ * BounceBan Email Verification Provider
+ *
+ * Specializes in catch-all email verification with 85-95% accuracy
+ * using proprietary algorithms WITHOUT sending actual emails.
+ *
+ * Features:
+ * - Catch-all domain verification (industry-leading)
+ * - DeepVerify mode for pattern-guessed emails (+15-25% accuracy)
+ * - Waterfall endpoint with FREE 30-min retry window
+ * - Single email verification is FREE
+ * - GDPR compliant (no emails sent)
+ *
+ * API Endpoints:
+ * - GET /v1/verify/single - Standard single verification
+ * - GET https://api-waterfall.bounceban.com/v1/verify/single - Waterfall (recommended)
+ * - POST /v1/verify/bulk - Bulk verification
+ *
+ * Result values:
+ * - deliverable: Email verified (score 70-100)
+ * - risky: May work, often catch-all (score 30-70)
+ * - undeliverable: Email doesn't exist (score 0-30)
+ * - unknown: Could not determine
+ *
+ * @see https://bounceban.com
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createBounceBanProvider = createBounceBanProvider;
+exports.verifyEmailWithBounceBan = verifyEmailWithBounceBan;
+exports.verifyEmailsBatchWithBounceBan = verifyEmailsBatchWithBounceBan;
+exports.checkCatchAllWithBounceBan = checkCatchAllWithBounceBan;
+const http_retry_1 = require("../utils/http-retry");
+const noop_provider_1 = require("../utils/noop-provider");
+const DEFAULT_API_URL = "https://api.bounceban.com";
+const DEFAULT_WATERFALL_API_URL = "https://api-waterfall.bounceban.com";
+const DEFAULT_TIMEOUT_MS = 30000;
+const DEFAULT_WATERFALL_TIMEOUT_MS = 80000;
+/**
+ * Map BounceBan result to confidence score
+ */
+function resultToConfidence(result, score, isAcceptAll) {
+    // Use the score directly if provided (0-100)
+    if (score >= 0 && score <= 100) {
+        // Reduce confidence for catch-all domains
+        if (isAcceptAll && result === "deliverable") {
+            return Math.min(score, 75); // Cap at 75 for catch-all even if deliverable
+        }
+        return score;
+    }
+    // Fallback based on result type
+    switch (result) {
+        case "deliverable":
+            return isAcceptAll ? 70 : 95;
+        case "risky":
+            return isAcceptAll ? 50 : 60;
+        case "undeliverable":
+            return 10;
+        case "unknown":
+        default:
+            return 30;
+    }
+}
+/**
+ * Map BounceBan result to verified status
+ */
+function resultToVerified(result) {
+    switch (result) {
+        case "deliverable":
+            return true;
+        case "undeliverable":
+            return false;
+        case "risky":
+        case "unknown":
+        default:
+            return undefined; // Can't determine
+    }
+}
+/**
+ * Extract emails to verify from candidate
+ * BounceBan is a VERIFICATION provider - 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"));
+    }
+    // Also check for a single email field
+    const singleEmail = candidate.email;
+    if (typeof singleEmail === "string" && singleEmail.includes("@")) {
+        emails.push(singleEmail);
+    }
+    return [...new Set(emails)]; // Deduplicate
+}
+/**
+ * Verify a single email via BounceBan standard endpoint
+ */
+async function verifyEmailStandard(email, apiKey, apiUrl, timeoutMs, useDeepVerify) {
+    const params = new URLSearchParams({
+        api_key: apiKey,
+        email: email,
+    });
+    if (useDeepVerify) {
+        params.set("mode", "deepverify");
+    }
+    try {
+        const response = await (0, http_retry_1.getWithRetry)(`${apiUrl}/v1/verify/single?${params.toString()}`, undefined, {
+            retries: 1,
+            backoffMs: 500,
+            timeoutMs,
+            retryOnStatus: [429, 500, 502, 503, 504],
+        });
+        return response;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Verify a single email via BounceBan waterfall endpoint
+ *
+ * The waterfall endpoint is optimized for:
+ * - Single HTTP request (no polling needed)
+ * - FREE retries within 30-min window if timeout
+ * - Better catch-all handling
+ */
+async function verifyEmailWaterfall(email, apiKey, waterfallApiUrl, timeoutMs, useDeepVerify) {
+    const params = new URLSearchParams({
+        api_key: apiKey,
+        email: email,
+        timeout: String(Math.floor(timeoutMs / 1000)), // Convert to seconds
+    });
+    if (useDeepVerify) {
+        params.set("mode", "deepverify");
+    }
+    try {
+        const response = await (0, http_retry_1.getWithRetry)(`${waterfallApiUrl}/v1/verify/single?${params.toString()}`, undefined, {
+            retries: 2, // Waterfall allows free retries within 30 mins
+            backoffMs: 5000, // Wait 5s between retries as recommended
+            timeoutMs: timeoutMs + 10000, // Add buffer for network
+            retryOnStatus: [408, 429, 500, 502, 503, 504], // Include 408 timeout
+        });
+        return response;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Create the BounceBan verification provider
+ *
+ * This provider specializes in verifying emails on catch-all domains
+ * where traditional SMTP verification fails.
+ *
+ * Best used after construct provider generates email patterns.
+ */
+function createBounceBanProvider(config) {
+    const { apiKey, apiUrl = DEFAULT_API_URL, waterfallApiUrl = DEFAULT_WATERFALL_API_URL, timeoutMs, useDeepVerify = false, useWaterfall = true, } = config;
+    // Determine timeout based on endpoint
+    const effectiveTimeout = timeoutMs ??
+        (useWaterfall ? DEFAULT_WATERFALL_TIMEOUT_MS : DEFAULT_TIMEOUT_MS);
+    if (!apiKey) {
+        return (0, noop_provider_1.createNoOpProvider)("bounceban");
+    }
+    /**
+     * Verify emails for a candidate
+     */
+    async function verifyEmails(candidate) {
+        const emailsToVerify = extractEmailsToVerify(candidate);
+        // If no emails to verify, return null
+        if (emailsToVerify.length === 0) {
+            return null;
+        }
+        const verifiedEmails = [];
+        // Verify each email
+        for (const email of emailsToVerify) {
+            // Add small delay between verifications to respect rate limits
+            if (verifiedEmails.length > 0) {
+                await (0, http_retry_1.delay)(200);
+            }
+            const result = useWaterfall
+                ? await verifyEmailWaterfall(email, apiKey, waterfallApiUrl, effectiveTimeout, useDeepVerify)
+                : await verifyEmailStandard(email, apiKey, apiUrl, effectiveTimeout, useDeepVerify);
+            if (!result || result.status !== "success") {
+                continue;
+            }
+            const confidence = resultToConfidence(result.result, result.score, result.is_accept_all);
+            const verified = resultToVerified(result.result);
+            // Only include potentially deliverable emails
+            if (result.result === "deliverable" || result.result === "risky") {
+                verifiedEmails.push({
+                    email: result.email,
+                    verified,
+                    confidence,
+                    isCatchAll: result.is_accept_all,
+                    metadata: {
+                        bounceBanResult: result.result,
+                        bounceBanScore: result.score,
+                        smtpProvider: result.smtp_provider,
+                        isDisposable: result.is_disposable,
+                        isRole: result.is_role,
+                        isFree: result.is_free,
+                        mxRecords: result.mx_records,
+                        mode: result.mode,
+                    },
+                });
+            }
+        }
+        if (verifiedEmails.length === 0) {
+            return null;
+        }
+        // Sort by confidence (highest first)
+        verifiedEmails.sort((a, b) => (b.confidence ?? 0) - (a.confidence ?? 0));
+        return { emails: verifiedEmails };
+    }
+    // Mark provider name for orchestrator
+    verifyEmails.__name = "bounceban";
+    return verifyEmails;
+}
+/**
+ * Standalone function to verify a single email via BounceBan
+ *
+ * Uses the waterfall endpoint by default for best catch-all handling.
+ *
+ * @example
+ * ```typescript
+ * const result = await verifyEmailWithBounceBan('john@catchall-domain.com', {
+ *   apiKey: process.env.BOUNCEBAN_API_KEY,
+ * });
+ * console.log(result.result); // "deliverable" | "risky" | "undeliverable" | "unknown"
+ * console.log(result.score); // 0-100
+ * console.log(result.is_accept_all); // true (catch-all domain)
+ * ```
+ */
+async function verifyEmailWithBounceBan(email, config) {
+    const { apiKey, waterfallApiUrl = DEFAULT_WATERFALL_API_URL, apiUrl = DEFAULT_API_URL, timeoutMs, useDeepVerify = false, useWaterfall = true, } = config;
+    if (!apiKey) {
+        return null;
+    }
+    const effectiveTimeout = timeoutMs ??
+        (useWaterfall ? DEFAULT_WATERFALL_TIMEOUT_MS : DEFAULT_TIMEOUT_MS);
+    return useWaterfall
+        ? verifyEmailWaterfall(email, apiKey, waterfallApiUrl, effectiveTimeout, useDeepVerify)
+        : verifyEmailStandard(email, apiKey, apiUrl, effectiveTimeout, useDeepVerify);
+}
+/**
+ * Submit emails for bulk verification via BounceBan
+ *
+ * @returns Task ID for polling status
+ */
+async function submitBulkVerification(emails, apiKey, apiUrl, useDeepVerify) {
+    try {
+        const response = await fetch(`${apiUrl}/v1/verify/bulk`, {
+            method: "POST",
+            headers: {
+                "Content-Type": "application/json",
+            },
+            body: JSON.stringify({
+                api_key: apiKey,
+                emails: emails,
+                mode: useDeepVerify ? "deepverify" : "regular",
+            }),
+        });
+        if (!response.ok) {
+            return null;
+        }
+        const data = (await response.json());
+        return data.id || null;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Check bulk verification task status
+ */
+async function checkBulkStatus(taskId, apiKey, apiUrl) {
+    try {
+        const params = new URLSearchParams({
+            api_key: apiKey,
+            id: taskId,
+        });
+        const response = await fetch(`${apiUrl}/v1/verify/bulk/status?${params.toString()}`);
+        if (!response.ok) {
+            return null;
+        }
+        return (await response.json());
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Fetch bulk verification results (paginated)
+ */
+async function fetchBulkResults(taskId, apiKey, apiUrl, page = 1, perPage = 100) {
+    try {
+        const response = await fetch(`${apiUrl}/v1/verify/bulk/dump`, {
+            method: "POST",
+            headers: {
+                "Content-Type": "application/json",
+            },
+            body: JSON.stringify({
+                api_key: apiKey,
+                id: taskId,
+                page: page,
+                per_page: perPage,
+            }),
+        });
+        if (!response.ok) {
+            return null;
+        }
+        return (await response.json());
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Verify multiple emails in batch via BounceBan Bulk API
+ *
+ * More cost-effective for large volumes ($0.003/email vs single free).
+ * Uses async bulk API with polling for results.
+ *
+ * For small batches (< 5 emails), falls back to sequential single verification.
+ *
+ * @example
+ * ```typescript
+ * const results = await verifyEmailsBatchWithBounceBan(
+ *   ['john@example.com', 'jane@example.com'],
+ *   { apiKey: process.env.BOUNCEBAN_API_KEY }
+ * );
+ * ```
+ */
+async function verifyEmailsBatchWithBounceBan(emails, config) {
+    const results = new Map();
+    const { apiKey, apiUrl = DEFAULT_API_URL, useDeepVerify = false } = config;
+    if (!apiKey || emails.length === 0) {
+        return results;
+    }
+    // For small batches, use sequential single verification (it's free)
+    if (emails.length < 5) {
+        for (const email of emails) {
+            const result = await verifyEmailWithBounceBan(email, config);
+            results.set(email, result);
+            // Small delay between requests
+            if (emails.indexOf(email) < emails.length - 1) {
+                await (0, http_retry_1.delay)(200);
+            }
+        }
+        return results;
+    }
+    // For larger batches, use bulk API
+    const taskId = await submitBulkVerification(emails, apiKey, apiUrl, useDeepVerify);
+    if (!taskId) {
+        // Fallback to sequential if bulk submit fails
+        for (const email of emails) {
+            const result = await verifyEmailWithBounceBan(email, config);
+            results.set(email, result);
+            if (emails.indexOf(email) < emails.length - 1) {
+                await (0, http_retry_1.delay)(200);
+            }
+        }
+        return results;
+    }
+    // Poll for completion (max 5 minutes)
+    const maxPollTime = 5 * 60 * 1000;
+    const pollInterval = 2000;
+    const startTime = Date.now();
+    while (Date.now() - startTime < maxPollTime) {
+        await (0, http_retry_1.delay)(pollInterval);
+        const status = await checkBulkStatus(taskId, apiKey, apiUrl);
+        if (!status) {
+            continue;
+        }
+        if (status.status === "error") {
+            // Bulk failed, return empty results
+            return results;
+        }
+        if (status.status === "finished") {
+            // Fetch all results with pagination
+            let page = 1;
+            const perPage = 100;
+            let hasMore = true;
+            while (hasMore) {
+                const dumpResponse = await fetchBulkResults(taskId, apiKey, apiUrl, page, perPage);
+                if (!dumpResponse || dumpResponse.results.length === 0) {
+                    hasMore = false;
+                    break;
+                }
+                // Map results to our response format
+                for (const item of dumpResponse.results) {
+                    const response = {
+                        id: taskId,
+                        status: "success",
+                        email: item.email,
+                        result: item.result,
+                        score: item.score,
+                        is_disposable: item.is_disposable,
+                        is_accept_all: item.is_accept_all,
+                        is_role: item.is_role,
+                        is_free: item.is_free,
+                        mx_records: item.mx_records,
+                        smtp_provider: item.smtp_provider,
+                    };
+                    results.set(item.email, response);
+                }
+                // Check if there are more pages
+                if (dumpResponse.results.length < perPage) {
+                    hasMore = false;
+                }
+                else {
+                    page++;
+                }
+            }
+            return results;
+        }
+        // Still processing, continue polling
+    }
+    // Timeout - return whatever we have
+    return results;
+}
+/**
+ * Check if a domain is catch-all via BounceBan
+ *
+ * Verifies a random non-existent email to detect catch-all behavior.
+ *
+ * @example
+ * ```typescript
+ * const isCatchAll = await checkCatchAllWithBounceBan('example.com', {
+ *   apiKey: process.env.BOUNCEBAN_API_KEY,
+ * });
+ * ```
+ */
+async function checkCatchAllWithBounceBan(domain, config) {
+    // Generate a random email that almost certainly doesn't exist
+    const randomLocal = `catchall-test-${Date.now()}-${Math.random().toString(36).slice(2, 10)}`;
+    const testEmail = `${randomLocal}@${domain}`;
+    const result = await verifyEmailWithBounceBan(testEmail, config);
+    if (!result) {
+        return null; // Could not determine
+    }
+    // If the random email is "deliverable" or "risky", the domain is catch-all
+    return result.is_accept_all || result.result === "deliverable";
+}

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

@@ -13,7 +13,7 @@
  *
  * @see https://docs.usebouncer.com
  */
-import type { EnrichmentCandidate, ProviderResult, ProviderMultiResult, BouncerConfig, BouncerVerifyResponse } from '../types';
+import type { EnrichmentCandidate, ProviderResult, ProviderMultiResult, BouncerConfig, BouncerVerifyResponse } from "../types";
 /**
  * Create the Bouncer verification provider
  *

package/dist/enrichment/providers/bouncer.js

@@ -19,14 +19,15 @@ exports.createBouncerProvider = createBouncerProvider;
 exports.verifyEmailWithBouncer = verifyEmailWithBouncer;
 exports.checkCatchAllDomain = checkCatchAllDomain;
 exports.verifyEmailsBatch = verifyEmailsBatch;
-const DEFAULT_API_URL = 'https://api.usebouncer.com/v1.1';
+const noop_provider_1 = require("../utils/noop-provider");
+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':
+        case "deliverable":
             // High confidence - email verified as deliverable
             // Reduce slightly if catch-all or high toxicity
             let score = 95;
@@ -37,13 +38,13 @@ function statusToConfidence(status, response) {
             if (response.role)
                 score -= 5; // Role accounts slightly lower
             return Math.max(50, score);
-        case 'risky':
+        case "risky":
             // Medium confidence - risky but might work
             return response.acceptAll ? 40 : 50;
-        case 'undeliverable':
+        case "undeliverable":
             // Email does not exist
             return 0;
-        case 'unknown':
+        case "unknown":
             // Could not verify
             return 30;
         default:
@@ -59,7 +60,7 @@ function extractEmailsToVerify(candidate) {
     // 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'));
+        emails.push(...metadata.filter((e) => typeof e === "string"));
     }
     return emails;
 }
@@ -72,10 +73,10 @@ async function verifyEmail(email, apiKey, apiUrl, timeoutMs) {
     try {
         const url = `${apiUrl}/email/verify?email=${encodeURIComponent(email)}`;
         const response = await fetch(url, {
-            method: 'GET',
+            method: "GET",
             headers: {
-                'x-api-key': apiKey,
-                'Accept': 'application/json',
+                "x-api-key": apiKey,
+                Accept: "application/json",
             },
             signal: controller.signal,
         });
@@ -83,7 +84,7 @@ async function verifyEmail(email, apiKey, apiUrl, timeoutMs) {
             // All HTTP errors return null - let caller decide how to handle
             return null;
         }
-        const data = await response.json();
+        const data = (await response.json());
         return data;
     }
     catch {
@@ -106,12 +107,9 @@ async function verifyEmail(email, apiKey, apiUrl, timeoutMs) {
  * 3. Only verified emails are returned
  */
 function createBouncerProvider(config) {
-    const { apiKey, apiUrl = DEFAULT_API_URL, timeoutMs = DEFAULT_TIMEOUT_MS } = 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;
+        return (0, noop_provider_1.createNoOpProvider)("bouncer");
     }
     async function verifyEmails(candidate) {
         const emailsToVerify = extractEmailsToVerify(candidate);
@@ -128,10 +126,10 @@ function createBouncerProvider(config) {
                 if (result) {
                     const confidence = statusToConfidence(result.status, result);
                     // Only include emails that are potentially deliverable
-                    if (result.status === 'deliverable' || result.status === 'risky') {
+                    if (result.status === "deliverable" || result.status === "risky") {
                         verifiedEmails.push({
                             email: result.email,
-                            verified: result.status === 'deliverable',
+                            verified: result.status === "deliverable",
                             confidence,
                             isCatchAll: result.acceptAll,
                             metadata: {
@@ -159,7 +157,7 @@ function createBouncerProvider(config) {
         return { emails: verifiedEmails };
     }
     // Mark provider name for orchestrator
-    verifyEmails.__name = 'bouncer';
+    verifyEmails.__name = "bouncer";
     return verifyEmails;
 }
 /**
@@ -176,7 +174,7 @@ function createBouncerProvider(config) {
  * ```
  */
 async function verifyEmailWithBouncer(email, config) {
-    const { apiKey, apiUrl = DEFAULT_API_URL, timeoutMs = DEFAULT_TIMEOUT_MS } = config;
+    const { apiKey, apiUrl = DEFAULT_API_URL, timeoutMs = DEFAULT_TIMEOUT_MS, } = config;
     return verifyEmail(email, apiKey, apiUrl, timeoutMs);
 }
 /**
@@ -192,7 +190,7 @@ async function verifyEmailWithBouncer(email, config) {
  * ```
  */
 async function checkCatchAllDomain(domain, config) {
-    const { apiKey, apiUrl = DEFAULT_API_URL, timeoutMs = DEFAULT_TIMEOUT_MS } = 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}`;
@@ -215,7 +213,7 @@ async function checkCatchAllDomain(domain, config) {
  * ```
  */
 async function verifyEmailsBatch(emails, config) {
-    const { apiKey, apiUrl = DEFAULT_API_URL, timeoutMs = DEFAULT_TIMEOUT_MS } = 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;

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

@@ -4,7 +4,7 @@
  * Generates email pattern candidates based on name + domain, then verifies via MX check.
  * This is a FREE provider that doesn't require any API keys.
  */
-import type { EnrichmentCandidate, ProviderResult, ProviderMultiResult, ConstructConfig } from '../types';
+import type { EnrichmentCandidate, ProviderResult, ProviderMultiResult, ConstructConfig } from "../types";
 /**
  * Create the construct provider function
  */