linkedin-secret-sauce 0.4.0 → 0.5.0

package/dist/enrichment/index.d.ts

@@ -0,0 +1,43 @@
+/**
+ * Email Enrichment Module
+ *
+ * Provides email enrichment capabilities with multiple provider support,
+ * waterfall orchestration, and configurable options.
+ *
+ * @example
+ * ```typescript
+ * import { createEnrichmentClient } from 'linkedin-secret-sauce';
+ *
+ * const enricher = createEnrichmentClient({
+ *   providers: {
+ *     hunter: { apiKey: process.env.HUNTER_API_KEY },
+ *     apollo: { apiKey: process.env.APOLLO_API_KEY },
+ *   },
+ *   options: {
+ *     maxCostPerEmail: 0.05,
+ *     confidenceThreshold: 50,
+ *   },
+ * });
+ *
+ * const result = await enricher.enrich({
+ *   firstName: 'John',
+ *   lastName: 'Doe',
+ *   company: 'Acme Corp',
+ * });
+ * ```
+ */
+import type { EnrichmentClientConfig, EnrichmentClient } from './types';
+/**
+ * Create an enrichment client with the given configuration
+ *
+ * @param config - Configuration for the enrichment client
+ * @returns An enrichment client with enrich and enrichBatch methods
+ */
+export declare function createEnrichmentClient(config: EnrichmentClientConfig): EnrichmentClient;
+export * from './types';
+export { isPersonalEmail, isBusinessEmail, isPersonalDomain, PERSONAL_DOMAINS, } from './utils/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 { enrichBusinessEmail, enrichBatch } from './orchestrator';

package/dist/enrichment/index.js

@@ -0,0 +1,231 @@
+"use strict";
+/**
+ * Email Enrichment Module
+ *
+ * Provides email enrichment capabilities with multiple provider support,
+ * waterfall orchestration, and configurable options.
+ *
+ * @example
+ * ```typescript
+ * import { createEnrichmentClient } from 'linkedin-secret-sauce';
+ *
+ * const enricher = createEnrichmentClient({
+ *   providers: {
+ *     hunter: { apiKey: process.env.HUNTER_API_KEY },
+ *     apollo: { apiKey: process.env.APOLLO_API_KEY },
+ *   },
+ *   options: {
+ *     maxCostPerEmail: 0.05,
+ *     confidenceThreshold: 50,
+ *   },
+ * });
+ *
+ * const result = await enricher.enrich({
+ *   firstName: 'John',
+ *   lastName: 'Doe',
+ *   company: 'Acme Corp',
+ * });
+ * ```
+ */
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+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.enrichBatch = exports.enrichBusinessEmail = 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.createEnrichmentClient = createEnrichmentClient;
+const orchestrator_1 = require("./orchestrator");
+const construct_1 = require("./providers/construct");
+const ldd_1 = require("./providers/ldd");
+const smartprospect_1 = require("./providers/smartprospect");
+const hunter_1 = require("./providers/hunter");
+const apollo_1 = require("./providers/apollo");
+const dropcontact_1 = require("./providers/dropcontact");
+/**
+ * Default provider order
+ */
+const DEFAULT_ORDER = [
+    'construct',
+    'ldd',
+    'smartprospect',
+    'hunter',
+    'apollo',
+    'dropcontact',
+];
+/**
+ * Create an enrichment client with the given configuration
+ *
+ * @param config - Configuration for the enrichment client
+ * @returns An enrichment client with enrich and enrichBatch methods
+ */
+function createEnrichmentClient(config) {
+    const { providers: providerConfigs, options = {}, cache, onCost, logger } = config;
+    // Build provider functions based on configuration
+    const providerFuncs = new Map();
+    // Always create construct provider (free, no API key needed)
+    providerFuncs.set('construct', (0, construct_1.createConstructProvider)(providerConfigs.construct));
+    // Create other providers if configured
+    if (providerConfigs.ldd) {
+        providerFuncs.set('ldd', (0, ldd_1.createLddProvider)(providerConfigs.ldd));
+    }
+    if (providerConfigs.smartprospect) {
+        providerFuncs.set('smartprospect', (0, smartprospect_1.createSmartProspectProvider)(providerConfigs.smartprospect));
+    }
+    if (providerConfigs.hunter) {
+        providerFuncs.set('hunter', (0, hunter_1.createHunterProvider)(providerConfigs.hunter));
+    }
+    if (providerConfigs.apollo) {
+        providerFuncs.set('apollo', (0, apollo_1.createApolloProvider)(providerConfigs.apollo));
+    }
+    if (providerConfigs.dropcontact) {
+        providerFuncs.set('dropcontact', (0, dropcontact_1.createDropcontactProvider)(providerConfigs.dropcontact));
+    }
+    // Build ordered provider list
+    const providerOrder = options.providerOrder ?? DEFAULT_ORDER;
+    const orderedProviders = [];
+    for (const name of providerOrder) {
+        const provider = providerFuncs.get(name);
+        if (provider) {
+            orderedProviders.push(provider);
+        }
+    }
+    // Orchestrator options
+    const orchestratorOptions = {
+        providers: orderedProviders,
+        maxCostPerEmail: options.maxCostPerEmail,
+        confidenceThreshold: options.confidenceThreshold,
+        retryMs: options.retryMs,
+        onCost,
+        logger,
+    };
+    return {
+        /**
+         * Enrich a single candidate with business email
+         */
+        async enrich(candidate) {
+            // Check cache first
+            if (cache) {
+                const cacheKey = buildCacheKey(candidate);
+                if (cacheKey) {
+                    try {
+                        const cached = await cache.get(cacheKey);
+                        if (cached) {
+                            logger?.debug?.('enrichment.cache.hit', { cacheKey });
+                            return cached;
+                        }
+                    }
+                    catch {
+                        // Ignore cache errors
+                    }
+                }
+            }
+            // Run enrichment
+            const result = await (0, orchestrator_1.enrichBusinessEmail)(candidate, orchestratorOptions);
+            // Store in cache
+            if (cache && result.business_email) {
+                const cacheKey = buildCacheKey(candidate);
+                if (cacheKey) {
+                    try {
+                        await cache.set(cacheKey, result, 30 * 24 * 60 * 60 * 1000); // 30 days TTL
+                    }
+                    catch {
+                        // Ignore cache errors
+                    }
+                }
+            }
+            return result;
+        },
+        /**
+         * Enrich multiple candidates in batches
+         */
+        async enrichBatch(candidates, batchOptions) {
+            return (0, orchestrator_1.enrichBatch)(candidates, {
+                ...orchestratorOptions,
+                ...batchOptions,
+            });
+        },
+    };
+}
+/**
+ * Build a cache key from candidate data
+ */
+function buildCacheKey(candidate) {
+    const parts = [];
+    // Use LinkedIn URL/username as primary key if available
+    const linkedinUrl = candidate.linkedinUrl || candidate.linkedin_url;
+    const linkedinUsername = candidate.linkedinUsername || candidate.linkedin_username;
+    const linkedinId = candidate.linkedinId || candidate.linkedin_id;
+    if (linkedinUrl) {
+        parts.push(`li:${linkedinUrl}`);
+    }
+    else if (linkedinUsername) {
+        parts.push(`li:${linkedinUsername}`);
+    }
+    else if (linkedinId) {
+        parts.push(`li:${linkedinId}`);
+    }
+    else {
+        // Fall back to name + domain/company
+        const firstName = candidate.firstName || candidate.first_name || candidate.first || '';
+        const lastName = candidate.lastName || candidate.last_name || candidate.last || '';
+        const domain = candidate.domain || candidate.companyDomain || candidate.company_domain || '';
+        const company = candidate.company || candidate.currentCompany || candidate.organization || '';
+        if (firstName && (domain || company)) {
+            parts.push(`name:${firstName.toLowerCase()}`);
+            if (lastName)
+                parts.push(lastName.toLowerCase());
+            if (domain)
+                parts.push(`dom:${domain.toLowerCase()}`);
+            else if (company)
+                parts.push(`co:${company.toLowerCase()}`);
+        }
+    }
+    if (parts.length === 0) {
+        return null;
+    }
+    return parts.join('|');
+}
+// Re-export types
+__exportStar(require("./types"), exports);
+// Re-export utilities
+var personal_domains_1 = require("./utils/personal-domains");
+Object.defineProperty(exports, "isPersonalEmail", { enumerable: true, get: function () { return personal_domains_1.isPersonalEmail; } });
+Object.defineProperty(exports, "isBusinessEmail", { enumerable: true, get: function () { return personal_domains_1.isBusinessEmail; } });
+Object.defineProperty(exports, "isPersonalDomain", { enumerable: true, get: function () { return personal_domains_1.isPersonalDomain; } });
+Object.defineProperty(exports, "PERSONAL_DOMAINS", { enumerable: true, get: function () { return personal_domains_1.PERSONAL_DOMAINS; } });
+var disposable_domains_1 = require("./utils/disposable-domains");
+Object.defineProperty(exports, "isDisposableEmail", { enumerable: true, get: function () { return disposable_domains_1.isDisposableEmail; } });
+Object.defineProperty(exports, "isDisposableDomain", { enumerable: true, get: function () { return disposable_domains_1.isDisposableDomain; } });
+Object.defineProperty(exports, "DISPOSABLE_DOMAINS", { enumerable: true, get: function () { return disposable_domains_1.DISPOSABLE_DOMAINS; } });
+var validation_1 = require("./utils/validation");
+Object.defineProperty(exports, "isValidEmailSyntax", { enumerable: true, get: function () { return validation_1.isValidEmailSyntax; } });
+Object.defineProperty(exports, "isRoleAccount", { enumerable: true, get: function () { return validation_1.isRoleAccount; } });
+Object.defineProperty(exports, "asciiFold", { enumerable: true, get: function () { return validation_1.asciiFold; } });
+Object.defineProperty(exports, "cleanNamePart", { enumerable: true, get: function () { return validation_1.cleanNamePart; } });
+Object.defineProperty(exports, "hostnameFromUrl", { enumerable: true, get: function () { return validation_1.hostnameFromUrl; } });
+Object.defineProperty(exports, "extractLinkedInUsername", { enumerable: true, get: function () { return validation_1.extractLinkedInUsername; } });
+// Re-export verification
+var mx_1 = require("./verification/mx");
+Object.defineProperty(exports, "verifyEmailMx", { enumerable: true, get: function () { return mx_1.verifyEmailMx; } });
+// Re-export providers (for advanced usage)
+var providers_1 = require("./providers");
+Object.defineProperty(exports, "createConstructProvider", { enumerable: true, get: function () { return providers_1.createConstructProvider; } });
+Object.defineProperty(exports, "createLddProvider", { enumerable: true, get: function () { return providers_1.createLddProvider; } });
+Object.defineProperty(exports, "createSmartProspectProvider", { enumerable: true, get: function () { return providers_1.createSmartProspectProvider; } });
+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; } });
+// Re-export orchestrator (for advanced usage)
+var orchestrator_2 = require("./orchestrator");
+Object.defineProperty(exports, "enrichBusinessEmail", { enumerable: true, get: function () { return orchestrator_2.enrichBusinessEmail; } });
+Object.defineProperty(exports, "enrichBatch", { enumerable: true, get: function () { return orchestrator_2.enrichBatch; } });

package/dist/enrichment/orchestrator.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Email Enrichment Waterfall Orchestrator
+ *
+ * Runs providers in sequence until a verified email is found that meets
+ * the confidence threshold. Supports budget tracking and cost callbacks.
+ */
+import type { CanonicalEmail, EnrichmentCandidate, ProviderFunc, BatchEnrichmentOptions, CostCallback, EnrichmentLogger } from './types';
+export interface OrchestratorOptions {
+    /** Provider functions in order */
+    providers: ProviderFunc[];
+    /** Maximum cost per email in USD */
+    maxCostPerEmail?: number;
+    /** Minimum confidence threshold (0-100) */
+    confidenceThreshold?: number;
+    /** Retry delay in ms */
+    retryMs?: number;
+    /** Cost callback */
+    onCost?: CostCallback;
+    /** Logger */
+    logger?: EnrichmentLogger;
+}
+/**
+ * Enrich a single candidate with business email
+ */
+export declare function enrichBusinessEmail(candidate: EnrichmentCandidate, options: OrchestratorOptions): Promise<CanonicalEmail>;
+/**
+ * Enrich multiple candidates in batches
+ */
+export declare function enrichBatch(candidates: EnrichmentCandidate[], options: OrchestratorOptions & BatchEnrichmentOptions): Promise<Array<{
+    candidate: EnrichmentCandidate;
+} & CanonicalEmail>>;

package/dist/enrichment/orchestrator.js

@@ -0,0 +1,218 @@
+"use strict";
+/**
+ * Email Enrichment Waterfall Orchestrator
+ *
+ * Runs providers in sequence until a verified email is found that meets
+ * the confidence threshold. Supports budget tracking and cost callbacks.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.enrichBusinessEmail = enrichBusinessEmail;
+exports.enrichBatch = enrichBatch;
+const personal_domains_1 = require("./utils/personal-domains");
+const disposable_domains_1 = require("./utils/disposable-domains");
+/**
+ * Default provider costs in USD per lookup
+ */
+const DEFAULT_PROVIDER_COSTS = {
+    construct: 0,
+    ldd: 0,
+    smartprospect: 0.01,
+    hunter: 0.005,
+    apollo: 0,
+    dropcontact: 0.01,
+};
+/**
+ * Normalize provider result to canonical format
+ */
+function normalizeProviderResult(providerName, raw) {
+    const iso = new Date().toISOString();
+    // No result from provider
+    if (!raw || !raw.email) {
+        return {
+            business_email: null,
+            business_email_source: providerName,
+            business_email_verified: false,
+            last_checked_at: iso,
+        };
+    }
+    const email = String(raw.email);
+    const confidence = typeof raw.score === 'number'
+        ? raw.score
+        : typeof raw.confidence === 'number'
+            ? raw.confidence
+            : undefined;
+    const verified = Boolean(raw.verified);
+    return {
+        business_email: email,
+        business_email_source: providerName,
+        business_email_verified: verified,
+        business_email_confidence: confidence,
+        last_checked_at: iso,
+    };
+}
+/**
+ * Get provider name from function
+ */
+function getProviderName(provider, index) {
+    return provider.__name ?? `provider-${index}`;
+}
+/**
+ * Get provider cost
+ */
+function getProviderCost(providerName) {
+    return DEFAULT_PROVIDER_COSTS[providerName] ?? 0;
+}
+/**
+ * Enrich a single candidate with business email
+ */
+async function enrichBusinessEmail(candidate, options) {
+    const { providers, maxCostPerEmail = Infinity, confidenceThreshold = 0, retryMs = 200, onCost, logger, } = options;
+    // Track remaining budget
+    let remaining = Number.isFinite(maxCostPerEmail) && maxCostPerEmail >= 0 ? maxCostPerEmail : Infinity;
+    logger?.debug?.('enrichment.start', {
+        providers: providers.length,
+        confidenceThreshold,
+        maxCostPerEmail,
+    });
+    for (let i = 0; i < providers.length; i++) {
+        const provider = providers[i];
+        const providerName = getProviderName(provider, i);
+        const stepCost = getProviderCost(providerName);
+        // Skip if cost exceeds remaining budget
+        if (stepCost > 0 && remaining < stepCost) {
+            logger?.debug?.('enrichment.skip_budget', {
+                provider: providerName,
+                cost: stepCost,
+                remaining,
+            });
+            continue;
+        }
+        let raw = null;
+        try {
+            logger?.debug?.('enrichment.provider.start', { provider: providerName });
+            raw = await provider(candidate);
+            logger?.debug?.('enrichment.provider.done', {
+                provider: providerName,
+                hasResult: !!raw?.email,
+            });
+        }
+        catch (error) {
+            logger?.warn?.('enrichment.provider.error', {
+                provider: providerName,
+                error: error instanceof Error ? error.message : String(error),
+            });
+            // Retry once after delay on transient errors
+            if (retryMs > 0) {
+                await new Promise((r) => setTimeout(r, retryMs));
+                try {
+                    raw = await provider(candidate);
+                    logger?.debug?.('enrichment.provider.retry.done', {
+                        provider: providerName,
+                        hasResult: !!raw?.email,
+                    });
+                }
+                catch {
+                    raw = null;
+                }
+            }
+        }
+        // Deduct cost (even on failure - API was called)
+        if (stepCost > 0) {
+            remaining = Math.max(0, remaining - stepCost);
+            if (onCost) {
+                try {
+                    await onCost(providerName, stepCost);
+                }
+                catch {
+                    // Ignore cost callback errors
+                }
+            }
+            logger?.debug?.('enrichment.cost.debit', {
+                provider: providerName,
+                cost: stepCost,
+                remaining,
+            });
+        }
+        // Normalize result
+        const normalized = normalizeProviderResult(providerName, raw);
+        // Skip if no email found
+        if (!normalized.business_email) {
+            continue;
+        }
+        // Filter out personal emails
+        if ((0, personal_domains_1.isPersonalEmail)(normalized.business_email)) {
+            logger?.debug?.('enrichment.skip_personal', {
+                provider: providerName,
+                email: normalized.business_email,
+            });
+            continue;
+        }
+        // Filter out disposable emails
+        if ((0, disposable_domains_1.isDisposableEmail)(normalized.business_email)) {
+            logger?.debug?.('enrichment.skip_disposable', {
+                provider: providerName,
+                email: normalized.business_email,
+            });
+            continue;
+        }
+        // Check confidence threshold
+        const score = normalized.business_email_confidence;
+        if (confidenceThreshold > 0 && score !== undefined && score < confidenceThreshold) {
+            logger?.debug?.('enrichment.skip_low_confidence', {
+                provider: providerName,
+                score,
+                threshold: confidenceThreshold,
+            });
+            continue;
+        }
+        // Check if verified
+        if (!normalized.business_email_verified) {
+            logger?.debug?.('enrichment.skip_unverified', {
+                provider: providerName,
+                email: normalized.business_email,
+            });
+            continue;
+        }
+        // Success!
+        logger?.info?.('enrichment.success', {
+            provider: providerName,
+            email: normalized.business_email,
+            confidence: normalized.business_email_confidence,
+        });
+        return normalized;
+    }
+    // No provider found a valid email
+    logger?.debug?.('enrichment.not_found', {
+        candidateHasName: !!(candidate.firstName || candidate.name),
+        candidateHasDomain: !!(candidate.domain || candidate.company),
+    });
+    return {
+        business_email: null,
+        business_email_source: null,
+        business_email_verified: false,
+        last_checked_at: new Date().toISOString(),
+        status: 'not_found',
+    };
+}
+/**
+ * Enrich multiple candidates in batches
+ */
+async function enrichBatch(candidates, options) {
+    const results = [];
+    const batchSize = options.batchSize ?? 50;
+    const delayMs = options.delayMs ?? 200;
+    for (let i = 0; i < candidates.length; i += batchSize) {
+        const chunk = candidates.slice(i, i + batchSize);
+        // Process batch in parallel
+        const batchResults = await Promise.all(chunk.map((candidate) => enrichBusinessEmail(candidate, options)));
+        // Combine results with candidates
+        batchResults.forEach((result, idx) => {
+            results.push({ candidate: chunk[idx], ...result });
+        });
+        // Delay between batches to avoid rate limiting
+        if (i + batchSize < candidates.length && delayMs > 0) {
+            await new Promise((r) => setTimeout(r, delayMs));
+        }
+    }
+    return results;
+}

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

@@ -0,0 +1,11 @@
+/**
+ * Apollo.io Provider
+ *
+ * Apollo.io public API for email finding.
+ * Uses mixed_people/search endpoint.
+ */
+import type { EnrichmentCandidate, ProviderResult, ApolloConfig } from "../types";
+/**
+ * Create the Apollo provider function
+ */
+export declare function createApolloProvider(config: ApolloConfig): (candidate: EnrichmentCandidate) => Promise<ProviderResult | null>;

package/dist/enrichment/providers/apollo.js

@@ -0,0 +1,136 @@
+"use strict";
+/**
+ * Apollo.io Provider
+ *
+ * Apollo.io public API for email finding.
+ * Uses mixed_people/search endpoint.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createApolloProvider = createApolloProvider;
+const API_BASE = "https://api.apollo.io/v1";
+/**
+ * Delay helper for retry logic
+ */
+async function delay(ms) {
+    return new Promise((r) => setTimeout(r, ms));
+}
+/**
+ * Check if value is truthy
+ */
+function truthy(v) {
+    return v !== undefined && v !== null && String(v).length > 0;
+}
+/**
+ * Map Apollo verification status to boolean
+ */
+function mapVerified(status) {
+    if (!status)
+        return undefined;
+    const s = String(status).toLowerCase();
+    if (s === "verified" || s === "deliverable")
+        return true;
+    if (s === "invalid" || s === "undeliverable")
+        return false;
+    return undefined;
+}
+/**
+ * HTTP request with retry on 429 rate limit
+ */
+async function requestWithRetry(url, init, retries = 1, backoffMs = 200) {
+    let lastErr;
+    for (let i = 0; i <= retries; i++) {
+        try {
+            const res = await fetch(url, init);
+            // Retry on rate limit
+            if (res?.status === 429 && i < retries) {
+                await delay(backoffMs * Math.pow(2, i));
+                continue;
+            }
+            if (!res || res.status >= 400) {
+                lastErr = new Error(`apollo_http_${res?.status ?? "error"}`);
+                break;
+            }
+            const json = (await res.json());
+            return json;
+        }
+        catch (err) {
+            lastErr = err;
+            if (i < retries) {
+                await delay(backoffMs * Math.pow(2, i));
+                continue;
+            }
+        }
+    }
+    throw lastErr ?? new Error("apollo_http_error");
+}
+/**
+ * Extract inputs from candidate
+ */
+function extractInputs(candidate) {
+    const name = candidate.name || candidate.full_name || candidate.fullName || undefined;
+    const org = candidate.company || candidate.organization || candidate.org || undefined;
+    const domain = candidate.domain ||
+        candidate.companyDomain ||
+        candidate.company_domain ||
+        undefined;
+    return { name, org, domain };
+}
+/**
+ * Create the Apollo provider function
+ */
+function createApolloProvider(config) {
+    const { apiKey } = config;
+    if (!apiKey) {
+        // Return a no-op provider if not configured
+        const noopProvider = async () => null;
+        noopProvider.__name = "apollo";
+        return noopProvider;
+    }
+    async function fetchEmail(candidate) {
+        const { name, org, domain } = extractInputs(candidate);
+        // Build request body
+        const body = { page: 1, per_page: 1 };
+        if (truthy(name))
+            body["q_person_name"] = String(name);
+        if (truthy(domain))
+            body["organization_domains"] = [String(domain)];
+        else if (truthy(org))
+            body["q_organization_name"] = String(org);
+        const url = `${API_BASE}/mixed_people/search`;
+        const init = {
+            method: "POST",
+            headers: {
+                "content-type": "application/json",
+                "X-Api-Key": String(apiKey),
+            },
+            body: JSON.stringify(body),
+        };
+        try {
+            const json = await requestWithRetry(url, init, 1, 100);
+            // Parse response - handle multiple possible shapes
+            const people = (json &&
+                (json.people || json.matches || json.data?.people));
+            if (!Array.isArray(people) || people.length === 0)
+                return null;
+            const p = people[0] || {};
+            const email = p.email ??
+                p.primary_email ??
+                p.emails?.[0]?.email ??
+                null;
+            if (!email)
+                return null;
+            const score = typeof p.email_confidence === "number"
+                ? p.email_confidence
+                : Number(p.email_confidence ?? 0) || undefined;
+            const verified = mapVerified(p.email_status ??
+                p.emails?.[0]?.status);
+            return { email, verified, score };
+        }
+        catch {
+            return null;
+        }
+    }
+    // Mark provider name for orchestrator
+    fetchEmail.__name = "apollo";
+    return fetchEmail;
+}

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

@@ -0,0 +1,11 @@
+/**
+ * Email Construction Provider
+ *
+ * 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, ConstructConfig } from '../types';
+/**
+ * Create the construct provider function
+ */
+export declare function createConstructProvider(config?: ConstructConfig): (candidate: EnrichmentCandidate) => Promise<ProviderResult | null>;