linkedin-secret-sauce 0.12.1 → 0.12.3

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

@@ -24,10 +24,20 @@ export interface CanonicalEmail {
 /**
  * Raw result from a provider before normalization
  */
+/**
+ * Result returned by a single-email provider
+ */
 export interface ProviderResult {
+    /** The email address found */
     email?: string | null;
+    /** Whether the email was verified */
     verified?: boolean;
+    /**
+     * Confidence score (0-100)
+     * @deprecated Use `confidence` instead - both are supported for backwards compatibility
+     */
     score?: number;
+    /** Confidence score (0-100) */
     confidence?: number;
 }
 /**
@@ -112,6 +122,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 +173,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
  *
@@ -293,10 +497,14 @@ export interface ProvidersConfig {
     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;
 }
@@ -377,22 +585,25 @@ export interface EnrichmentClient {
 /**
  * Available provider names
  */
-export type ProviderName = "construct" | "ldd" | "smartprospect" | "cosiall" | "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[];
 /**
@@ -402,7 +613,9 @@ export declare const DEFAULT_PROVIDER_ORDER: ProviderName[];
  * - 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

package/dist/enrichment/types.js

@@ -8,29 +8,33 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.SMARTPROSPECT_SUB_INDUSTRIES = exports.PROVIDER_COSTS = exports.DEFAULT_PROVIDER_ORDER = void 0;
 /**
- * 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
  */
 exports.DEFAULT_PROVIDER_ORDER = [
     "ldd",
     "smartprospect",
     "cosiall",
+    "trykitt",
     "construct",
-    "bouncer",
-    "snovio",
+    "bounceban",
     "hunter",
+    "snovio",
 ];
 /**
  * Provider costs in USD per lookup
@@ -39,7 +43,9 @@ exports.DEFAULT_PROVIDER_ORDER = [
  * - 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
@@ -50,6 +56,8 @@ exports.PROVIDER_COSTS = {
     ldd: 0,
     smartprospect: 0,
     cosiall: 0,
+    trykitt: 0, // FREE for individuals
+    bounceban: 0.003, // FREE single, $0.003 bulk
     hunter: 0.005,
     dropcontact: 0.01,
     bouncer: 0.006,

package/dist/enrichment/utils/candidate-parser.d.ts

@@ -0,0 +1,107 @@
+/**
+ * Shared Candidate Parsing Utilities
+ *
+ * Extracts common fields from EnrichmentCandidate objects.
+ * Reduces code duplication across providers by centralizing field extraction logic.
+ */
+import type { EnrichmentCandidate } from "../types";
+/**
+ * Parsed name components from a candidate
+ */
+export interface ParsedName {
+    firstName: string;
+    lastName: string;
+    fullName: string;
+}
+/**
+ * Parsed company/domain info from a candidate
+ */
+export interface ParsedCompany {
+    company: string | null;
+    domain: string | null;
+}
+/**
+ * Parsed LinkedIn identifiers from a candidate
+ */
+export interface ParsedLinkedIn {
+    /** LinkedIn username/handle (e.g., "john-doe") */
+    username: string | null;
+    /** LinkedIn profile URL */
+    url: string | null;
+    /** Numeric LinkedIn ID (stable, never changes) */
+    numericId: string | null;
+}
+/**
+ * Full parsed candidate with all extracted fields
+ */
+export interface ParsedCandidate {
+    name: ParsedName;
+    company: ParsedCompany;
+    linkedin: ParsedLinkedIn;
+    title: string | null;
+}
+/**
+ * Extract name components from a candidate
+ *
+ * Checks multiple field naming conventions:
+ * - firstName, first_name, first
+ * - lastName, last_name, last
+ * - name, fullName, full_name (split on space)
+ */
+export declare function extractName(candidate: EnrichmentCandidate): ParsedName;
+/**
+ * Extract company and domain from a candidate
+ *
+ * Checks multiple field naming conventions:
+ * - company, currentCompany, organization, org
+ * - domain, companyDomain, company_domain
+ */
+export declare function extractCompany(candidate: EnrichmentCandidate): ParsedCompany;
+/**
+ * Extract LinkedIn username from a URL
+ *
+ * Handles various URL formats:
+ * - https://linkedin.com/in/john-doe
+ * - https://www.linkedin.com/in/john-doe/
+ * - linkedin.com/in/john-doe?param=value
+ */
+export declare function extractLinkedInUsernameFromUrl(url: string | undefined | null): string | null;
+/**
+ * Extract numeric LinkedIn ID from various formats
+ *
+ * Handles:
+ * - Direct numeric ID: "307567"
+ * - URN format: "urn:li:member:307567"
+ * - Sales profile URN: "urn:li:fs_salesProfile:(307567,...)"
+ */
+export declare function extractNumericLinkedInId(input: string | undefined | null): string | null;
+/**
+ * Extract LinkedIn identifiers from a candidate
+ *
+ * Returns username, URL, and numeric ID (if available).
+ * Numeric ID is preferred for lookups as it never changes.
+ */
+export declare function extractLinkedIn(candidate: EnrichmentCandidate): ParsedLinkedIn;
+/**
+ * Extract job title from a candidate
+ */
+export declare function extractTitle(candidate: EnrichmentCandidate): string | null;
+/**
+ * Parse all common fields from a candidate
+ *
+ * Use this for a complete extraction of all fields at once.
+ * For partial extraction, use the individual functions.
+ */
+export declare function parseCandidate(candidate: EnrichmentCandidate): ParsedCandidate;
+/**
+ * Build a LinkedIn URL from a username/handle
+ */
+export declare function buildLinkedInUrl(username: string): string;
+/**
+ * Check if a candidate has minimum required fields for email lookup
+ *
+ * @param candidate - The candidate to check
+ * @param requireDomain - Whether domain is required (default: true)
+ * @returns true if candidate has at least name and optionally domain
+ */
+export declare function hasMinimumFields(candidate: EnrichmentCandidate, requireDomain?: boolean): boolean;