linkedin-secret-sauce 0.4.0 → 0.5.1

package/dist/enrichment/types.d.ts

@@ -0,0 +1,343 @@
+/**
+ * Email Enrichment Types
+ *
+ * Core types for the email enrichment module. These types are designed to be
+ * stateless - consumers pass their own API keys and configuration.
+ */
+/**
+ * Canonical email result returned by enrichment operations
+ */
+export interface CanonicalEmail {
+    /** The found business email, or null if not found */
+    business_email: string | null;
+    /** Which provider found the email */
+    business_email_source: string | null;
+    /** Whether the email was verified */
+    business_email_verified: boolean;
+    /** Confidence score (0-100) */
+    business_email_confidence?: number;
+    /** ISO timestamp of when the check was performed */
+    last_checked_at: string;
+    /** Status for debugging */
+    status?: string;
+}
+/**
+ * Raw result from a provider before normalization
+ */
+export interface ProviderResult {
+    email?: string | null;
+    verified?: boolean;
+    score?: number;
+    confidence?: number;
+}
+/**
+ * Provider function signature
+ */
+export type ProviderFunc = (candidate: EnrichmentCandidate) => Promise<ProviderResult | null>;
+/**
+ * Input candidate for enrichment - flexible to accept various naming conventions
+ */
+export interface EnrichmentCandidate {
+    firstName?: string;
+    first_name?: string;
+    first?: string;
+    lastName?: string;
+    last_name?: string;
+    last?: string;
+    name?: string;
+    fullName?: string;
+    full_name?: string;
+    company?: string;
+    currentCompany?: string;
+    organization?: string;
+    org?: string;
+    domain?: string;
+    companyDomain?: string;
+    company_domain?: string;
+    linkedinUsername?: string;
+    linkedin_username?: string;
+    linkedinUrl?: string;
+    linkedin_url?: string;
+    linkedinId?: string;
+    linkedin_id?: string;
+    title?: string;
+    currentRole?: string;
+    current_role?: string;
+}
+/**
+ * Hunter.io provider configuration
+ */
+export interface HunterConfig {
+    apiKey: string;
+}
+/**
+ * Apollo.io provider configuration
+ */
+export interface ApolloConfig {
+    apiKey: string;
+}
+/**
+ * SmartProspect/Smartlead provider configuration
+ *
+ * Supports two auth methods:
+ * 1. Direct token: Pass `apiToken` directly
+ * 2. Credentials: Pass `email` and `password` for auto-login with token caching
+ */
+export interface SmartProspectConfig {
+    /** Direct API/JWT token (if you already have one) */
+    apiToken?: string;
+    /** SmartLead account email (for credentials-based auth) */
+    email?: string;
+    /** SmartLead account password (for credentials-based auth) */
+    password?: string;
+    /** API URL override (default: https://prospect-api.smartlead.ai/api/search-email-leads) */
+    apiUrl?: string;
+    /** Login URL override (default: https://server.smartlead.ai/api/auth/login) */
+    loginUrl?: string;
+    /** Pre-fetch token on client creation (default: true) - ensures token is ready for first request */
+    eagerInit?: boolean;
+}
+/**
+ * LinkedIn Data Dump provider configuration
+ */
+export interface LddConfig {
+    apiUrl: string;
+    apiToken: string;
+}
+/**
+ * Dropcontact provider configuration
+ */
+export interface DropcontactConfig {
+    apiKey: string;
+}
+/**
+ * Email construction provider configuration (no API key needed)
+ */
+export interface ConstructConfig {
+    /** Maximum email pattern attempts (default: 8) */
+    maxAttempts?: number;
+    /** Timeout for MX verification in ms (default: 5000) */
+    timeoutMs?: number;
+}
+/**
+ * All provider configurations
+ */
+export interface ProvidersConfig {
+    construct?: ConstructConfig;
+    ldd?: LddConfig;
+    smartprospect?: SmartProspectConfig;
+    hunter?: HunterConfig;
+    apollo?: ApolloConfig;
+    dropcontact?: DropcontactConfig;
+}
+/**
+ * Options for enrichment operations
+ */
+export interface EnrichmentOptions {
+    /** Maximum cost per email enrichment in USD (default: Infinity) */
+    maxCostPerEmail?: number;
+    /** Minimum confidence threshold 0-100 (default: 0) */
+    confidenceThreshold?: number;
+    /** Provider order (default: ['construct', 'ldd', 'smartprospect', 'hunter', 'apollo', 'dropcontact']) */
+    providerOrder?: ProviderName[];
+    /** Retry delay in ms on transient errors (default: 200) */
+    retryMs?: number;
+}
+/**
+ * Options for batch enrichment
+ */
+export interface BatchEnrichmentOptions extends EnrichmentOptions {
+    /** Batch size for parallel processing (default: 50) */
+    batchSize?: number;
+    /** Delay between batches in ms (default: 200) */
+    delayMs?: number;
+}
+/**
+ * Cache adapter interface - consumers provide their own caching implementation
+ */
+export interface CacheAdapter {
+    /** Get cached result for an email */
+    get: (email: string) => Promise<CanonicalEmail | null>;
+    /** Set cached result for an email */
+    set: (email: string, result: CanonicalEmail, ttlMs?: number) => Promise<void>;
+}
+/**
+ * Cost callback - called when a provider incurs a cost
+ */
+export type CostCallback = (provider: string, costUsd: number) => void | Promise<void>;
+/**
+ * Logger interface - consumers can provide their own logger
+ */
+export interface EnrichmentLogger {
+    debug?: (message: string, context?: Record<string, unknown>) => void;
+    info?: (message: string, context?: Record<string, unknown>) => void;
+    warn?: (message: string, context?: Record<string, unknown>) => void;
+    error?: (message: string, context?: Record<string, unknown>) => void;
+}
+/**
+ * Configuration for createEnrichmentClient
+ */
+export interface EnrichmentClientConfig {
+    /** Provider API keys and configuration */
+    providers: ProvidersConfig;
+    /** Enrichment options */
+    options?: EnrichmentOptions;
+    /** Optional cache adapter */
+    cache?: CacheAdapter;
+    /** Optional cost tracking callback */
+    onCost?: CostCallback;
+    /** Optional logger */
+    logger?: EnrichmentLogger;
+}
+/**
+ * Enrichment client interface
+ */
+export interface EnrichmentClient {
+    /** Enrich a single candidate */
+    enrich: (candidate: EnrichmentCandidate) => Promise<CanonicalEmail>;
+    /** Enrich multiple candidates in batches */
+    enrichBatch: (candidates: EnrichmentCandidate[], options?: BatchEnrichmentOptions) => Promise<Array<{
+        candidate: EnrichmentCandidate;
+    } & CanonicalEmail>>;
+}
+/**
+ * Available provider names
+ */
+export type ProviderName = "construct" | "ldd" | "smartprospect" | "hunter" | "apollo" | "dropcontact";
+/**
+ * Default provider order
+ */
+export declare const DEFAULT_PROVIDER_ORDER: ProviderName[];
+/**
+ * Provider costs in USD per lookup
+ */
+export declare const PROVIDER_COSTS: Record<ProviderName, number>;
+/**
+ * Email verification result
+ */
+export interface VerificationResult {
+    /** Whether the email is valid */
+    valid: boolean | null;
+    /** Confidence score 0-100 */
+    confidence: number;
+    /** Reason for the result */
+    reason?: "valid" | "invalid" | "syntax" | "mx_missing" | "disposable" | "role_account" | "catch_all" | "timeout" | "error";
+    /** Whether this is a catch-all domain */
+    isCatchAll: boolean;
+    /** Whether this is a role account (info@, support@, etc.) */
+    isRoleAccount: boolean;
+    /** Whether this is a disposable email */
+    isDisposable: boolean;
+    /** MX records found */
+    mxRecords?: string[];
+}
+export interface SmartProspectCompany {
+    name: string;
+    website: string;
+}
+export interface SmartProspectContact {
+    id: string;
+    firstName: string;
+    lastName: string;
+    fullName: string;
+    title: string;
+    company: SmartProspectCompany;
+    department: string[];
+    level: string;
+    industry: string;
+    subIndustry: string;
+    companyHeadCount: string;
+    companyRevenue: string;
+    country: string;
+    state: string;
+    city: string;
+    email: string;
+    emailSource?: string;
+    linkedin: string;
+    emailDeliverability: number;
+    address: string;
+    status?: string;
+    verificationStatus?: string;
+    catchAllStatus?: string;
+}
+export interface SmartProspectSearchFilters {
+    name?: string[];
+    firstName?: string[];
+    lastName?: string[];
+    title?: string[];
+    company?: string[];
+    domain?: string[];
+    department?: string[];
+    level?: string[];
+    industry?: string[];
+    country?: string[];
+    state?: string[];
+    city?: string[];
+    companyHeadCount?: string[];
+    companyRevenue?: string[];
+    dontDisplayOwnedContact?: boolean;
+    limit?: number;
+    titleExactMatch?: boolean;
+    scroll_id?: string;
+}
+export interface SmartProspectSearchResponse {
+    success: boolean;
+    message: string;
+    data: {
+        list: SmartProspectContact[];
+        scroll_id?: string;
+        filter_id?: number;
+        total_count: number;
+    };
+}
+export interface SmartProspectFetchResponse {
+    success: boolean;
+    message: string;
+    data: {
+        list: SmartProspectContact[];
+        total_count: number;
+        metrics: {
+            totalContacts: number;
+            totalEmails: number;
+            noEmailFound: number;
+            invalidEmails: number;
+            catchAllEmails: number;
+            verifiedEmails: number;
+            completed: number;
+        };
+        leads_found: number;
+        email_fetched: number;
+        verification_status_list: string[];
+    };
+}
+export interface LddProfileEmail {
+    email_address: string;
+    email_type?: string | null;
+}
+export interface LddProfilePhone {
+    phone_number: string;
+    phone_type?: string | null;
+}
+export interface LddProfileData {
+    source_record_id: string;
+    linkedin_profile_url?: string | null;
+    linkedin_id?: string | null;
+    linkedin_username?: string | null;
+    first_name?: string | null;
+    last_name?: string | null;
+    full_name?: string | null;
+    profile_headline?: string | null;
+    profile_summary?: string | null;
+    profile_location?: string | null;
+    emails: LddProfileEmail[];
+    phones: LddProfilePhone[];
+}
+export type LddApiResponse = {
+    success: true;
+    data: LddProfileData;
+} | {
+    success: false;
+    error: string;
+    message: string;
+    statusCode?: number;
+};

package/dist/enrichment/types.js

@@ -0,0 +1,31 @@
+"use strict";
+/**
+ * Email Enrichment Types
+ *
+ * Core types for the email enrichment module. These types are designed to be
+ * stateless - consumers pass their own API keys and configuration.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PROVIDER_COSTS = exports.DEFAULT_PROVIDER_ORDER = void 0;
+/**
+ * Default provider order
+ */
+exports.DEFAULT_PROVIDER_ORDER = [
+    "construct",
+    "ldd",
+    "smartprospect",
+    "hunter",
+    "apollo",
+    "dropcontact",
+];
+/**
+ * Provider costs in USD per lookup
+ */
+exports.PROVIDER_COSTS = {
+    construct: 0,
+    ldd: 0,
+    smartprospect: 0.01,
+    hunter: 0.005,
+    apollo: 0,
+    dropcontact: 0.01,
+};

package/dist/enrichment/utils/disposable-domains.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Disposable Email Domain Detection
+ *
+ * Detects disposable/temporary email domains (Mailinator, Guerrillamail, etc.)
+ * that should be filtered out when enriching emails.
+ */
+/**
+ * Set of known disposable email domains (600+)
+ */
+export declare const DISPOSABLE_DOMAINS: Set<string>;
+/**
+ * Check if an email is from a disposable domain
+ *
+ * @param email - Email address to check
+ * @returns true if the email is from a disposable domain
+ */
+export declare function isDisposableEmail(email: string): boolean;
+/**
+ * Check if a domain is a disposable email domain
+ *
+ * @param domain - Domain to check
+ * @returns true if the domain is a disposable email domain
+ */
+export declare function isDisposableDomain(domain: string): boolean;