linkedin-secret-sauce 0.12.0 → 0.12.2

package/dist/enrichment/providers/trykitt.js

@@ -0,0 +1,210 @@
+"use strict";
+/**
+ * TryKitt.ai Email Finder Provider
+ *
+ * AI-powered email finding with enterprise identity server verification.
+ * FREE for individuals with unlimited searches.
+ *
+ * Features:
+ * - Email finding by name + domain
+ * - Enterprise identity server catch-all verification (more accurate than SMTP)
+ * - <0.1% bounce rate claimed
+ * - 2-5x faster than traditional SMTP verification
+ *
+ * API Endpoints:
+ * - POST /job/find-email - Find email by name + domain
+ * - POST /job/verify-email - Verify existing email
+ *
+ * Rate Limits (Free tier):
+ * - 2 requests/second
+ * - 120 requests/minute
+ * - Unlimited monthly quota
+ *
+ * @see https://trykitt.ai
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createTryKittProvider = createTryKittProvider;
+exports.findEmailWithTryKitt = findEmailWithTryKitt;
+exports.verifyEmailWithTryKitt = verifyEmailWithTryKitt;
+const http_retry_1 = require("../utils/http-retry");
+const candidate_parser_1 = require("../utils/candidate-parser");
+const noop_provider_1 = require("../utils/noop-provider");
+const DEFAULT_API_URL = "https://api.trykitt.ai";
+const DEFAULT_TIMEOUT_MS = 30000;
+/**
+ * Extract TryKitt-specific inputs from candidate using shared parser
+ */
+function extractTryKittInputs(candidate) {
+    const name = (0, candidate_parser_1.extractName)(candidate);
+    const { domain } = (0, candidate_parser_1.extractCompany)(candidate);
+    const linkedin = (0, candidate_parser_1.extractLinkedIn)(candidate);
+    // Build LinkedIn URL from username if URL not available
+    const linkedinUrl = linkedin.url ||
+        (linkedin.username ? (0, candidate_parser_1.buildLinkedInUrl)(linkedin.username) : null);
+    return {
+        fullName: name.fullName || null,
+        firstName: name.firstName || null,
+        lastName: name.lastName || null,
+        domain,
+        linkedinUrl,
+    };
+}
+/**
+ * Map TryKitt confidence to our 0-100 scale
+ * TryKitt returns confidence as 0-1 decimal OR 0-100 percentage
+ */
+function normalizeConfidence(confidence) {
+    // If confidence is <= 1, treat as decimal and convert to percentage
+    if (confidence <= 1) {
+        return Math.round(confidence * 100);
+    }
+    // Already a percentage
+    return Math.round(confidence);
+}
+/**
+ * Create the TryKitt.ai email finder provider
+ *
+ * This provider uses TryKitt's AI-powered email finding with enterprise
+ * identity server verification for catch-all domains.
+ */
+function createTryKittProvider(config) {
+    const { apiKey, apiUrl = DEFAULT_API_URL, timeoutMs = DEFAULT_TIMEOUT_MS, } = config;
+    if (!apiKey) {
+        return (0, noop_provider_1.createNoOpProvider)("trykitt");
+    }
+    /**
+     * Find email for a candidate
+     */
+    async function findEmail(candidate) {
+        const { fullName, domain, linkedinUrl } = extractTryKittInputs(candidate);
+        // Need at least name and domain to search
+        if (!(0, http_retry_1.truthy)(fullName) || !(0, http_retry_1.truthy)(domain)) {
+            return null;
+        }
+        try {
+            // Build request body
+            const body = {
+                full_name: fullName,
+                domain: domain,
+            };
+            // Add LinkedIn URL if available (improves accuracy)
+            if (linkedinUrl) {
+                body.linkedin_url = linkedinUrl;
+            }
+            const response = await (0, http_retry_1.postWithRetry)(`${apiUrl}/job/find-email`, body, {
+                Authorization: `Bearer ${apiKey}`,
+            }, {
+                retries: 2,
+                backoffMs: 500,
+                timeoutMs,
+                retryOnStatus: [429, 500, 502, 503, 504],
+            });
+            // Check if job completed successfully
+            if (response.status !== "completed") {
+                return null;
+            }
+            // Check if email was found
+            if (!response.result || !response.result.email) {
+                return null;
+            }
+            const result = response.result;
+            // Map confidence score
+            const confidence = normalizeConfidence(result.confidence_score ?? result.confidence ?? 0);
+            // Determine verification status
+            // TryKitt verifies emails, so if confidence is high, consider verified
+            const verified = confidence >= 80 &&
+                result.verification_type !== "unverified" &&
+                !result.is_catchall;
+            return {
+                email: result.email,
+                verified,
+                score: confidence,
+            };
+        }
+        catch {
+            // Silently fail - let other providers try
+            return null;
+        }
+    }
+    // Mark provider name for orchestrator
+    findEmail.__name = "trykitt";
+    return findEmail;
+}
+/**
+ * Standalone function to find email via TryKitt.ai
+ *
+ * @example
+ * ```typescript
+ * const result = await findEmailWithTryKitt('John Doe', 'example.com', {
+ *   apiKey: process.env.TRYKITT_API_KEY,
+ * });
+ * console.log(result?.email); // john.doe@example.com
+ * ```
+ */
+async function findEmailWithTryKitt(fullName, domain, config, linkedinUrl) {
+    const { apiKey, apiUrl = DEFAULT_API_URL, timeoutMs = DEFAULT_TIMEOUT_MS, } = config;
+    if (!apiKey) {
+        return null;
+    }
+    try {
+        const body = {
+            full_name: fullName,
+            domain: domain,
+        };
+        if (linkedinUrl) {
+            body.linkedin_url = linkedinUrl;
+        }
+        const response = await (0, http_retry_1.postWithRetry)(`${apiUrl}/job/find-email`, body, {
+            Authorization: `Bearer ${apiKey}`,
+        }, {
+            retries: 2,
+            backoffMs: 500,
+            timeoutMs,
+        });
+        return response;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Verify an email address via TryKitt.ai
+ *
+ * @example
+ * ```typescript
+ * const result = await verifyEmailWithTryKitt('john@example.com', {
+ *   apiKey: process.env.TRYKITT_API_KEY,
+ * });
+ * console.log(result?.result?.valid); // true
+ * console.log(result?.result?.is_catchall); // false
+ * ```
+ */
+async function verifyEmailWithTryKitt(email, config) {
+    const { apiKey, apiUrl = DEFAULT_API_URL, timeoutMs = DEFAULT_TIMEOUT_MS, } = config;
+    if (!apiKey) {
+        return null;
+    }
+    try {
+        const response = await (0, http_retry_1.postWithRetry)(`${apiUrl}/job/verify-email`, { email }, {
+            Authorization: `Bearer ${apiKey}`,
+        }, {
+            retries: 2,
+            backoffMs: 500,
+            timeoutMs,
+        });
+        if (response.status !== "completed" || !response.result) {
+            return null;
+        }
+        return {
+            valid: response.result.valid,
+            deliverable: response.result.deliverable,
+            confidence: normalizeConfidence(response.result.confidence),
+            isCatchAll: response.result.is_catchall ?? false,
+            isDisposable: response.result.is_disposable ?? false,
+            isRoleAccount: response.result.is_role_account ?? false,
+        };
+    }
+    catch {
+        return null;
+    }
+}

package/dist/enrichment/types.d.ts

@@ -45,7 +45,7 @@ export interface ProviderMultiResult {
 /**
  * Email type classification
  */
-export type EmailType = 'business' | 'personal' | 'disposable' | 'role' | 'unknown';
+export type EmailType = "business" | "personal" | "disposable" | "role" | "unknown";
 /**
  * Individual enriched email with full metadata
  */
@@ -112,6 +112,9 @@ export interface EnrichmentCandidate {
     linkedin_url?: string;
     linkedinId?: string;
     linkedin_id?: string;
+    /** LinkedIn handle/vanity (e.g., "john-doe" from linkedin.com/in/john-doe) - best for Hunter.io */
+    linkedinHandle?: string;
+    linkedin_handle?: string;
     numericLinkedInId?: string;
     numeric_linkedin_id?: string;
     objectUrn?: string;
@@ -160,6 +163,197 @@ export interface LddConfig {
 export interface DropcontactConfig {
     apiKey: string;
 }
+/**
+ * TryKitt.ai provider configuration
+ *
+ * TryKitt.ai provides AI-powered email finding with enterprise identity server
+ * verification for catch-all domains. FREE for individuals, unlimited searches.
+ *
+ * Features:
+ * - Email finding by name + domain
+ * - Enterprise identity server catch-all verification
+ * - <0.1% bounce rate claimed
+ * - 2-5x faster than traditional SMTP verification
+ *
+ * @see https://trykitt.ai
+ */
+export interface TryKittConfig {
+    /** TryKitt API key (Bearer token) */
+    apiKey: string;
+    /** API URL override (default: https://api.trykitt.ai) */
+    apiUrl?: string;
+    /** Timeout in ms (default: 30000) */
+    timeoutMs?: number;
+}
+/**
+ * TryKitt.ai find email response result
+ */
+export interface TryKittFindEmailResult {
+    /** Found email address */
+    email: string;
+    /** First name */
+    first_name?: string;
+    /** Last name */
+    last_name?: string;
+    /** Domain searched */
+    domain: string;
+    /** Confidence score (0-1 decimal or 0-100 percentage) */
+    confidence: number;
+    /** Confidence as percentage (0-100) */
+    confidence_score?: number;
+    /** Sources used to find email */
+    sources?: string[];
+    /** Verification type: "smtp_verified", "enterprise_identity_server", etc. */
+    verification_type?: string;
+    /** Whether domain is catch-all */
+    is_catchall?: boolean;
+    /** Whether email is a role account (info@, support@) */
+    is_role_account?: boolean;
+    /** Company name if found */
+    company?: string;
+    /** Job title if found */
+    title?: string;
+}
+/**
+ * TryKitt.ai API response for find-email endpoint
+ */
+export interface TryKittFindEmailResponse {
+    /** Job ID */
+    id: string;
+    /** Status: "completed", "pending", "failed" */
+    status: string;
+    /** When job was created */
+    created_at: string;
+    /** When job completed */
+    completed_at?: string;
+    /** Result data (null if not found) */
+    result: TryKittFindEmailResult | null;
+    /** Error message if failed */
+    error?: string;
+    /** Error code */
+    error_code?: string;
+    /** Custom data passed in request */
+    custom_data?: Record<string, unknown>;
+}
+/**
+ * TryKitt.ai verify email response result
+ */
+export interface TryKittVerifyEmailResult {
+    /** Email verified */
+    email: string;
+    /** Whether email is valid */
+    valid: boolean;
+    /** Whether email is deliverable */
+    deliverable: boolean;
+    /** Confidence score (0-1) */
+    confidence: number;
+    /** Verification type used */
+    verification_type?: string;
+    /** Whether domain is catch-all */
+    is_catchall?: boolean;
+    /** Whether email is disposable */
+    is_disposable?: boolean;
+    /** Whether email is a role account */
+    is_role_account?: boolean;
+    /** Whether email is from free provider (Gmail, Yahoo) */
+    is_free_email?: boolean;
+    /** SMTP status */
+    smtp_status?: string;
+    /** Bounce type: "none", "soft", "hard" */
+    bounce_type?: string;
+    /** Suggested correction for typos */
+    suggestion?: string;
+    /** Whether domain has MX records */
+    domain_mx?: boolean;
+    /** Whether domain has SPF record */
+    domain_spf?: boolean;
+    /** Whether domain has DMARC record */
+    domain_dmarc?: boolean;
+}
+/**
+ * TryKitt.ai API response for verify-email endpoint
+ */
+export interface TryKittVerifyEmailResponse {
+    /** Job ID */
+    id: string;
+    /** Status: "completed", "pending", "failed" */
+    status: string;
+    /** When job was created */
+    created_at: string;
+    /** When job completed */
+    completed_at?: string;
+    /** Result data */
+    result: TryKittVerifyEmailResult | null;
+    /** Custom data passed in request */
+    custom_data?: Record<string, unknown>;
+}
+/**
+ * BounceBan provider configuration
+ *
+ * BounceBan 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
+ * - Waterfall endpoint with free 30-min retry window
+ * - Single email verification is FREE
+ *
+ * @see https://bounceban.com
+ */
+export interface BounceBanConfig {
+    /** BounceBan API key */
+    apiKey: string;
+    /** API URL override (default: https://api.bounceban.com) */
+    apiUrl?: string;
+    /** Waterfall API URL (default: https://api-waterfall.bounceban.com) */
+    waterfallApiUrl?: string;
+    /** Timeout in ms (default: 80000 for waterfall, 30000 for standard) */
+    timeoutMs?: number;
+    /** Use DeepVerify mode when company domain is confirmed (default: false) */
+    useDeepVerify?: boolean;
+    /** Use waterfall endpoint for better catch-all handling (default: true) */
+    useWaterfall?: boolean;
+}
+/**
+ * BounceBan verification result
+ */
+export type BounceBanResult = "deliverable" | "risky" | "undeliverable" | "unknown";
+/**
+ * BounceBan API response for single verification
+ */
+export interface BounceBanVerifyResponse {
+    /** Unique verification ID */
+    id: string;
+    /** Status: "success", "pending", "error" */
+    status: string;
+    /** Email that was verified */
+    email: string;
+    /** Verification result */
+    result: BounceBanResult;
+    /** Deliverability score (0-100) */
+    score: number;
+    /** Whether email is from disposable domain */
+    is_disposable: boolean;
+    /** Whether domain is catch-all (accept-all) */
+    is_accept_all: boolean;
+    /** Whether email is a role account */
+    is_role: boolean;
+    /** Whether email is from free provider */
+    is_free: boolean;
+    /** MX records for the domain */
+    mx_records?: string[];
+    /** SMTP provider name (e.g., "Google", "Microsoft") */
+    smtp_provider?: string;
+    /** Verification mode used */
+    mode?: "regular" | "deepverify";
+    /** When verification completed */
+    verify_at?: string;
+    /** Credits consumed for this verification */
+    credits_consumed?: number;
+    /** Remaining credits */
+    credits_remaining?: number;
+}
 /**
  * Bouncer.io provider configuration
  *
@@ -179,11 +373,11 @@ export interface BouncerConfig {
 /**
  * Bouncer verification result status
  */
-export type BouncerStatus = 'deliverable' | 'undeliverable' | 'risky' | 'unknown';
+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';
+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
  */
@@ -232,7 +426,7 @@ export interface SnovioConfig {
 /**
  * Snov.io email verification status
  */
-export type SnovioVerificationStatus = 'valid' | 'not_valid' | 'catch_all' | 'unverifiable' | 'unknown';
+export type SnovioVerificationStatus = "valid" | "not_valid" | "catch_all" | "unverifiable" | "unknown";
 /**
  * Snov.io email result
  */
@@ -244,7 +438,7 @@ export interface SnovioEmailResult {
     position?: string;
     sourcePage?: string;
     companyName?: string;
-    type?: 'prospect' | 'personal';
+    type?: "prospect" | "personal";
     status?: string;
 }
 /**
@@ -274,6 +468,16 @@ export interface ConstructConfig {
     /** Delay between SMTP verification checks in ms (default: 2000) */
     smtpVerifyDelayMs?: number;
 }
+/**
+ * Cosiall Profile Emails provider configuration
+ *
+ * Uses Cosiall FlexIQ Profile Emails API to lookup emails for LinkedIn profiles.
+ * This is FREE - no API key needed (uses global Cosiall config).
+ */
+export interface CosiallConfig {
+    /** Whether to enable the provider (default: true) */
+    enabled?: boolean;
+}
 /**
  * All provider configurations
  */
@@ -281,10 +485,16 @@ export interface ProvidersConfig {
     construct?: ConstructConfig;
     ldd?: LddConfig;
     smartprospect?: SmartProspectConfig;
+    /** Cosiall Profile Emails (FREE - uses global Cosiall config) */
+    cosiall?: CosiallConfig;
+    /** TryKitt.ai AI email finder (FREE for individuals, unlimited) */
+    trykitt?: TryKittConfig;
     hunter?: HunterConfig;
     dropcontact?: DropcontactConfig;
     /** Bouncer.io for SMTP email verification (99%+ accuracy) */
     bouncer?: BouncerConfig;
+    /** BounceBan catch-all verification (FREE single, 85-95% accuracy) */
+    bounceban?: BounceBanConfig;
     /** Snov.io for email finding (98% delivery rate) */
     snovio?: SnovioConfig;
 }
@@ -365,21 +575,25 @@ export interface EnrichmentClient {
 /**
  * Available provider names
  */
-export type ProviderName = "construct" | "ldd" | "smartprospect" | "hunter" | "dropcontact" | "bouncer" | "snovio";
+export type ProviderName = "construct" | "ldd" | "smartprospect" | "cosiall" | "trykitt" | "hunter" | "dropcontact" | "bouncer" | "bounceban" | "snovio";
 /**
- * Default provider order - 2-Phase Strategy
+ * Default provider order - 3-Phase Strategy
  *
  * PHASE 1 - Free lookups (run in parallel):
  *   - ldd: LinkedIn Data Dump - real verified emails (FREE with subscription)
  *   - smartprospect: SmartLead API - real verified emails (FREE with subscription)
+ *   - cosiall: Cosiall Profile Emails - emails from LinkedIn profiles (FREE)
+ *   - trykitt: TryKitt.ai - AI email finder (FREE for individuals, unlimited)
+ *
+ * PHASE 2 - Pattern guessing + verification (if Phase 1 < 80% confidence):
  *   - construct: Pattern guessing + MX check (FREE)
+ *   - bounceban: BounceBan catch-all verification (FREE single, $0.003/bulk)
  *
- * PHASE 2 - Paid verification/finding (only if Phase 1 inconclusive):
- *   - bouncer: SMTP verify constructed emails ($0.006/email)
- *   - snovio: Email finder for catch-all domains ($0.02/email)
- *   - hunter: Hunter.io fallback ($0.005/email)
+ * PHASE 3 - Paid finders (only if Phase 2 inconclusive):
+ *   - hunter: Hunter.io email finder ($0.005/email)
+ *   - snovio: Snov.io email finder ($0.02/email)
  *
- * Note: dropcontact available but not in default order (expensive at $0.01)
+ * Note: bouncer, dropcontact available but not in default order
  */
 export declare const DEFAULT_PROVIDER_ORDER: ProviderName[];
 /**
@@ -388,7 +602,10 @@ export declare const DEFAULT_PROVIDER_ORDER: ProviderName[];
  * Costs based on 2025 pricing:
  * - ldd: FREE (subscription-based)
  * - smartprospect: FREE (included in SmartLead subscription)
+ * - cosiall: FREE (uses global Cosiall config)
+ * - trykitt: FREE (unlimited for individuals, $0.005/email high volume)
  * - construct: FREE (pattern guessing + MX check)
+ * - bounceban: FREE single / $0.003/email bulk (catch-all specialist)
  * - bouncer: $0.006/email (SMTP verification, 99%+ accuracy)
  * - snovio: $0.02/email (email finding + verification)
  * - hunter: $0.005/email
@@ -492,23 +709,23 @@ export interface SmartProspectSearchFilters {
 /**
  * SmartProspect Department values (exact API values)
  */
-export type SmartProspectDepartment = 'Engineering' | 'Finance & Administration' | 'Human Resources' | 'IT & IS' | 'Marketing' | 'Operations' | 'Other' | 'Support' | 'Sales';
+export type SmartProspectDepartment = "Engineering" | "Finance & Administration" | "Human Resources" | "IT & IS" | "Marketing" | "Operations" | "Other" | "Support" | "Sales";
 /**
  * SmartProspect Level/Seniority values (exact API values)
  */
-export type SmartProspectLevel = 'Staff' | 'Manager-Level' | 'Director-Level' | 'VP-Level' | 'C-Level';
+export type SmartProspectLevel = "Staff" | "Manager-Level" | "Director-Level" | "VP-Level" | "C-Level";
 /**
  * SmartProspect Headcount ranges (exact API values)
  */
-export type SmartProspectHeadcount = '0 - 25' | '25 - 100' | '100 - 250' | '250 - 1000' | '1K - 10K' | '10K - 50K' | '50K - 100K' | '> 100K';
+export type SmartProspectHeadcount = "0 - 25" | "25 - 100" | "100 - 250" | "250 - 1000" | "1K - 10K" | "10K - 50K" | "50K - 100K" | "> 100K";
 /**
  * SmartProspect Revenue ranges (exact API values)
  */
-export type SmartProspectRevenue = '$0 - 1M' | '$1 - 10M' | '$10 - 50M' | '$50 - 100M' | '$100 - 250M' | '$250 - 500M' | '$500M - 1B' | '> $1B';
+export type SmartProspectRevenue = "$0 - 1M" | "$1 - 10M" | "$10 - 50M" | "$50 - 100M" | "$100 - 250M" | "$250 - 500M" | "$500M - 1B" | "> $1B";
 /**
  * SmartProspect Industry values (exact API values)
  */
-export type SmartProspectIndustry = 'Software & Internet' | 'Business Services' | 'Real Estate & Construction' | 'Financial Services' | 'Healthcare, Pharmaceuticals, & Biotech' | 'Retail' | 'Consumer Services' | 'Education' | 'Media & Entertainment' | 'Travel, Recreation, and Leisure' | 'Transportation & Storage' | 'Manufacturing' | 'Wholesale & Distribution' | 'Non-Profit' | 'Energy & Utilities' | 'Government' | 'Agriculture & Mining' | 'Computers & Electronics' | 'Telecommunications' | 'Other';
+export type SmartProspectIndustry = "Software & Internet" | "Business Services" | "Real Estate & Construction" | "Financial Services" | "Healthcare, Pharmaceuticals, & Biotech" | "Retail" | "Consumer Services" | "Education" | "Media & Entertainment" | "Travel, Recreation, and Leisure" | "Transportation & Storage" | "Manufacturing" | "Wholesale & Distribution" | "Non-Profit" | "Energy & Utilities" | "Government" | "Agriculture & Mining" | "Computers & Electronics" | "Telecommunications" | "Other";
 /**
  * SmartProspect Sub-Industry values (exact API values - partial list)
  * Note: This is a subset of available sub-industries. The API accepts many more.