linkedin-secret-sauce 0.11.0 → 0.12.0

package/dist/enrichment/providers/construct.js

@@ -87,6 +87,7 @@ function extractDomain(candidate) {
 function createConstructProvider(config) {
     const maxAttempts = config?.maxAttempts ?? 8;
     const timeoutMs = config?.timeoutMs ?? 5000;
+    const smtpVerifyDelayMs = config?.smtpVerifyDelayMs ?? 2000; // Delay between SMTP checks
     async function fetchEmail(candidate) {
         const { first, last } = extractNames(candidate);
         const domain = extractDomain(candidate);
@@ -100,22 +101,79 @@ function createConstructProvider(config) {
         }
         const candidates = buildCandidates({ first, last, domain });
         const max = Math.min(candidates.length, maxAttempts);
+        // First, check if domain is catch-all
+        const catchAllResult = await (0, mx_1.checkDomainCatchAll)(domain, { timeoutMs: 10000 });
+        const isCatchAll = catchAllResult.isCatchAll;
         // Collect ALL valid email patterns (not just first match)
         const validEmails = [];
-        for (let i = 0; i < max; i++) {
-            const email = candidates[i];
-            const verification = await (0, mx_1.verifyEmailMx)(email, { timeoutMs });
-            if (verification.valid === true && verification.confidence >= 50) {
-                validEmails.push({
-                    email,
-                    verified: true,
-                    confidence: verification.confidence,
-                    isCatchAll: verification.isCatchAll,
-                    metadata: {
-                        pattern: email.split('@')[0], // The local part pattern used
-                        mxRecords: verification.mxRecords,
-                    },
-                });
+        // Track all attempted patterns for debugging
+        const attemptedPatterns = [];
+        // If NOT catch-all, we can verify each email via SMTP
+        if (isCatchAll === false) {
+            // Verify emails one by one, stop when we find a valid one
+            const emailsToVerify = candidates.slice(0, max);
+            for (let i = 0; i < emailsToVerify.length; i++) {
+                const email = emailsToVerify[i];
+                // If we already found a valid email, skip the rest
+                if (validEmails.length > 0) {
+                    attemptedPatterns.push({ email, status: 'skipped' });
+                    continue;
+                }
+                // Add delay between checks (except first one)
+                if (i > 0) {
+                    await new Promise((resolve) => setTimeout(resolve, smtpVerifyDelayMs));
+                }
+                // Verify single email
+                const results = await (0, mx_1.verifyEmailsExist)([email], { delayMs: 0, timeoutMs });
+                const result = results[0];
+                if (result.exists === true) {
+                    // Email confirmed to exist!
+                    attemptedPatterns.push({ email, status: 'exists' });
+                    validEmails.push({
+                        email: result.email,
+                        verified: true,
+                        confidence: 95, // High confidence - SMTP verified
+                        isCatchAll: false,
+                        metadata: {
+                            pattern: result.email.split('@')[0],
+                            mxRecords: catchAllResult.mxRecords,
+                            smtpVerified: true,
+                            attemptedPatterns, // Include what was tried
+                        },
+                    });
+                    // Found one! Stop checking more
+                    break;
+                }
+                else if (result.exists === false) {
+                    attemptedPatterns.push({ email, status: 'not_found' });
+                }
+                else {
+                    attemptedPatterns.push({ email, status: 'unknown' });
+                }
+            }
+            // If no valid email found, include attempted patterns in metadata
+            if (validEmails.length === 0 && attemptedPatterns.length > 0) {
+                // Return null but could add metadata about attempts
+            }
+        }
+        else {
+            // Catch-all or unknown - fall back to MX verification only
+            for (let i = 0; i < max; i++) {
+                const email = candidates[i];
+                const verification = await (0, mx_1.verifyEmailMx)(email, { timeoutMs });
+                if (verification.valid === true && verification.confidence >= 50) {
+                    validEmails.push({
+                        email,
+                        verified: true,
+                        confidence: verification.confidence,
+                        isCatchAll: isCatchAll ?? undefined,
+                        metadata: {
+                            pattern: email.split('@')[0],
+                            mxRecords: verification.mxRecords,
+                            smtpVerified: false,
+                        },
+                    });
+                }
             }
         }
         if (validEmails.length === 0) {

package/dist/enrichment/providers/hunter.js

@@ -7,62 +7,8 @@
  */
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.createHunterProvider = createHunterProvider;
+const http_retry_1 = require("../utils/http-retry");
 const API_BASE = "https://api.hunter.io/v2";
-/**
- * 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 Hunter verification status to boolean
- */
-function mapVerified(status) {
-    if (!status)
-        return undefined;
-    const s = String(status).toLowerCase();
-    if (s === "valid" || s === "deliverable")
-        return true;
-    if (s === "invalid" || s === "undeliverable")
-        return false;
-    return undefined; // catch-all/unknown/webmail -> leave undefined
-}
-/**
- * HTTP request with retry on 429 rate limit
- */
-async function requestWithRetry(url, retries = 1, backoffMs = 200) {
-    let lastErr;
-    for (let i = 0; i <= retries; i++) {
-        try {
-            const res = await fetch(url);
-            // 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(`hunter_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("hunter_http_error");
-}
 /**
  * Extract name and domain from candidate
  */
@@ -99,7 +45,7 @@ function createHunterProvider(config) {
         let url = null;
         let isEmailFinder = false;
         // Use email-finder if we have name components
-        if (truthy(first) && truthy(last) && truthy(domain)) {
+        if ((0, http_retry_1.truthy)(first) && (0, http_retry_1.truthy)(last) && (0, http_retry_1.truthy)(domain)) {
             const qs = new URLSearchParams({
                 api_key: String(apiKey),
                 domain: String(domain),
@@ -110,7 +56,7 @@ function createHunterProvider(config) {
             isEmailFinder = true;
         }
         // Fall back to domain-search if only domain available (can return multiple)
-        else if (truthy(domain)) {
+        else if ((0, http_retry_1.truthy)(domain)) {
             const qs = new URLSearchParams({
                 api_key: String(apiKey),
                 domain: String(domain),
@@ -122,7 +68,7 @@ function createHunterProvider(config) {
             return null; // Can't search without domain
         }
         try {
-            const json = await requestWithRetry(url, 1, 100);
+            const json = await (0, http_retry_1.getWithRetry)(url, undefined, { retries: 1, backoffMs: 100 });
             // Parse email-finder response shape (single result)
             if (isEmailFinder) {
                 const ef = (json && (json.data || json.result));
@@ -131,7 +77,7 @@ function createHunterProvider(config) {
                     const score = typeof ef.score === "number"
                         ? ef.score
                         : Number(ef.score ?? 0) || undefined;
-                    const verified = mapVerified(ef?.verification?.status ?? ef?.status);
+                    const verified = (0, http_retry_1.mapVerifiedStatus)(ef?.verification?.status ?? ef?.status);
                     if (!email)
                         return null;
                     return { email, verified, score };
@@ -158,7 +104,7 @@ function createHunterProvider(config) {
                     const score = typeof hit?.confidence === "number"
                         ? hit.confidence
                         : Number(hit?.confidence ?? 0) || 50;
-                    const verified = mapVerified(hit?.verification?.status ?? hit?.status);
+                    const verified = (0, http_retry_1.mapVerifiedStatus)(hit?.verification?.status ?? hit?.status);
                     emails.push({
                         email,
                         verified,

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

@@ -5,7 +5,6 @@ export { createConstructProvider } from './construct';
 export { createLddProvider } from './ldd';
 export { createSmartProspectProvider } from './smartprospect';
 export { createHunterProvider } from './hunter';
-export { createApolloProvider } from './apollo';
 export { createDropcontactProvider } from './dropcontact';
 export { createBouncerProvider, verifyEmailWithBouncer, checkCatchAllDomain, verifyEmailsBatch } from './bouncer';
 export { createSnovioProvider, findEmailsWithSnovio, verifyEmailWithSnovio, clearSnovioTokenCache } from './snovio';

package/dist/enrichment/providers/index.js

@@ -3,7 +3,7 @@
  * Email Enrichment Providers
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.clearSnovioTokenCache = exports.verifyEmailWithSnovio = exports.findEmailsWithSnovio = exports.createSnovioProvider = exports.verifyEmailsBatch = exports.checkCatchAllDomain = exports.verifyEmailWithBouncer = exports.createBouncerProvider = exports.createDropcontactProvider = exports.createApolloProvider = exports.createHunterProvider = exports.createSmartProspectProvider = exports.createLddProvider = exports.createConstructProvider = void 0;
+exports.clearSnovioTokenCache = exports.verifyEmailWithSnovio = exports.findEmailsWithSnovio = exports.createSnovioProvider = exports.verifyEmailsBatch = exports.checkCatchAllDomain = exports.verifyEmailWithBouncer = exports.createBouncerProvider = exports.createDropcontactProvider = exports.createHunterProvider = exports.createSmartProspectProvider = exports.createLddProvider = exports.createConstructProvider = void 0;
 var construct_1 = require("./construct");
 Object.defineProperty(exports, "createConstructProvider", { enumerable: true, get: function () { return construct_1.createConstructProvider; } });
 var ldd_1 = require("./ldd");
@@ -12,8 +12,6 @@ var smartprospect_1 = require("./smartprospect");
 Object.defineProperty(exports, "createSmartProspectProvider", { enumerable: true, get: function () { return smartprospect_1.createSmartProspectProvider; } });
 var hunter_1 = require("./hunter");
 Object.defineProperty(exports, "createHunterProvider", { enumerable: true, get: function () { return hunter_1.createHunterProvider; } });
-var apollo_1 = require("./apollo");
-Object.defineProperty(exports, "createApolloProvider", { enumerable: true, get: function () { return apollo_1.createApolloProvider; } });
 var dropcontact_1 = require("./dropcontact");
 Object.defineProperty(exports, "createDropcontactProvider", { enumerable: true, get: function () { return dropcontact_1.createDropcontactProvider; } });
 var bouncer_1 = require("./bouncer");

package/dist/enrichment/providers/ldd.js

@@ -13,43 +13,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.extractNumericLinkedInId = extractNumericLinkedInId;
 exports.createLddProvider = createLddProvider;
 const validation_1 = require("../utils/validation");
-/**
- * Delay helper for retry logic
- */
-async function delay(ms) {
-    return new Promise((r) => setTimeout(r, ms));
-}
-/**
- * HTTP request with retry on 429 rate limit
- */
-async function requestWithRetry(url, token, retries = 1, backoffMs = 200) {
-    let lastErr;
-    for (let i = 0; i <= retries; i++) {
-        try {
-            const res = await fetch(url, {
-                method: "GET",
-                headers: {
-                    Authorization: `Bearer ${token}`,
-                    "Content-Type": "application/json",
-                },
-            });
-            // Retry on rate limit
-            if (res?.status === 429 && i < retries) {
-                await delay(backoffMs * Math.pow(2, i));
-                continue;
-            }
-            return res;
-        }
-        catch (err) {
-            lastErr = err;
-            if (i < retries) {
-                await delay(backoffMs * Math.pow(2, i));
-                continue;
-            }
-        }
-    }
-    throw lastErr ?? new Error("ldd_http_error");
-}
+const http_retry_1 = require("../utils/http-retry");
 /**
  * Extract numeric LinkedIn ID from various formats:
  * - Direct number: "307567"
@@ -162,11 +126,8 @@ function createLddProvider(config) {
     async function lookupByNumericId(numericId) {
         try {
             const endpoint = `${apiUrl}/api/v1/profiles/by-numeric-id/${encodeURIComponent(numericId)}`;
-            const response = await requestWithRetry(endpoint, apiToken, 1, 100);
-            if (!response.ok) {
-                return null;
-            }
-            return parseResponse(await response.json());
+            const response = await (0, http_retry_1.getWithRetry)(endpoint, { Authorization: `Bearer ${apiToken}` }, { retries: 1, backoffMs: 100 });
+            return parseResponse(response);
         }
         catch {
             return null;
@@ -175,11 +136,8 @@ function createLddProvider(config) {
     async function lookupByUsername(username) {
         try {
             const endpoint = `${apiUrl}/api/v1/profiles/by-username/${encodeURIComponent(username)}`;
-            const response = await requestWithRetry(endpoint, apiToken, 1, 100);
-            if (!response.ok) {
-                return null;
-            }
-            return parseResponse(await response.json());
+            const response = await (0, http_retry_1.getWithRetry)(endpoint, { Authorization: `Bearer ${apiToken}` }, { retries: 1, backoffMs: 100 });
+            return parseResponse(response);
         }
         catch {
             return null;

package/dist/enrichment/providers/smartprospect.js

@@ -17,13 +17,8 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.createSmartProspectProvider = createSmartProspectProvider;
 exports.createSmartProspectClient = createSmartProspectClient;
 const smartlead_auth_1 = require("../auth/smartlead-auth");
+const http_retry_1 = require("../utils/http-retry");
 const DEFAULT_API_URL = "https://prospect-api.smartlead.ai/api/search-email-leads";
-/**
- * Delay helper for retry logic
- */
-async function delay(ms) {
-    return new Promise((r) => setTimeout(r, ms));
-}
 const DEFAULT_POLLING_CONFIG = {
     initialDelay: 500,
     pollInterval: 1000,
@@ -40,7 +35,7 @@ async function requestWithRetry(url, options, retries = 2, backoffMs = 300) {
             const res = await fetch(url, options);
             // Retry on rate limit
             if (res.status === 429 && i < retries) {
-                await delay(backoffMs * Math.pow(2, i));
+                await (0, http_retry_1.delay)(backoffMs * Math.pow(2, i));
                 continue;
             }
             if (!res.ok) {
@@ -52,7 +47,7 @@ async function requestWithRetry(url, options, retries = 2, backoffMs = 300) {
         catch (err) {
             lastErr = err;
             if (i < retries) {
-                await delay(backoffMs * Math.pow(2, i));
+                await (0, http_retry_1.delay)(backoffMs * Math.pow(2, i));
                 continue;
             }
         }
@@ -214,7 +209,7 @@ function createSmartProspectProvider(config) {
     async function pollForContactResults(filterId, expectedCount) {
         const { initialDelay, pollInterval, maxAttempts, maxWaitTime } = DEFAULT_POLLING_CONFIG;
         const startTime = Date.now();
-        await delay(initialDelay);
+        await (0, http_retry_1.delay)(initialDelay);
         const makeRequest = async (token) => {
             return requestWithRetry(`${apiUrl}/get-contacts`, {
                 method: "POST",
@@ -243,13 +238,13 @@ function createSmartProspectProvider(config) {
                         return result;
                     }
                 }
-                await delay(pollInterval);
+                await (0, http_retry_1.delay)(pollInterval);
             }
             catch (err) {
                 if (err instanceof Error && err.message.includes("401") && hasCredentials) {
                     await handleAuthError();
                 }
-                await delay(pollInterval);
+                await (0, http_retry_1.delay)(pollInterval);
             }
         }
         // Return last result
@@ -628,7 +623,7 @@ function createSmartProspectClient(config) {
         const { initialDelay, pollInterval, maxAttempts, maxWaitTime } = pollingConfig;
         const startTime = Date.now();
         // Wait initial delay before first poll
-        await delay(initialDelay);
+        await (0, http_retry_1.delay)(initialDelay);
         const makeRequest = async (token) => {
             return requestWithRetry(`${apiUrl}/get-contacts`, {
                 method: "POST",
@@ -660,7 +655,7 @@ function createSmartProspectClient(config) {
                     }
                 }
                 // Wait before next poll
-                await delay(pollInterval);
+                await (0, http_retry_1.delay)(pollInterval);
             }
             catch (err) {
                 // On 401, clear token and retry
@@ -670,7 +665,7 @@ function createSmartProspectClient(config) {
                     await handleAuthError();
                 }
                 // Continue polling on errors
-                await delay(pollInterval);
+                await (0, http_retry_1.delay)(pollInterval);
             }
         }
         // Return last result even if not complete

package/dist/enrichment/types.d.ts

@@ -126,12 +126,6 @@ export interface EnrichmentCandidate {
 export interface HunterConfig {
     apiKey: string;
 }
-/**
- * Apollo.io provider configuration
- */
-export interface ApolloConfig {
-    apiKey: string;
-}
 /**
  * SmartProspect/Smartlead provider configuration
  *
@@ -277,6 +271,8 @@ export interface ConstructConfig {
     maxAttempts?: number;
     /** Timeout for MX verification in ms (default: 5000) */
     timeoutMs?: number;
+    /** Delay between SMTP verification checks in ms (default: 2000) */
+    smtpVerifyDelayMs?: number;
 }
 /**
  * All provider configurations
@@ -286,7 +282,6 @@ export interface ProvidersConfig {
     ldd?: LddConfig;
     smartprospect?: SmartProspectConfig;
     hunter?: HunterConfig;
-    apollo?: ApolloConfig;
     dropcontact?: DropcontactConfig;
     /** Bouncer.io for SMTP email verification (99%+ accuracy) */
     bouncer?: BouncerConfig;
@@ -301,7 +296,7 @@ export interface EnrichmentOptions {
     maxCostPerEmail?: number;
     /** Minimum confidence threshold 0-100 (default: 0) */
     confidenceThreshold?: number;
-    /** Provider order (default: ['construct', 'ldd', 'smartprospect', 'hunter', 'apollo', 'dropcontact']) */
+    /** Provider order (default: ['ldd', 'smartprospect', 'construct', 'bouncer', 'snovio', 'hunter']) */
     providerOrder?: ProviderName[];
     /** Retry delay in ms on transient errors (default: 200) */
     retryMs?: number;
@@ -370,30 +365,34 @@ export interface EnrichmentClient {
 /**
  * Available provider names
  */
-export type ProviderName = "construct" | "ldd" | "smartprospect" | "hunter" | "apollo" | "dropcontact" | "bouncer" | "snovio";
+export type ProviderName = "construct" | "ldd" | "smartprospect" | "hunter" | "dropcontact" | "bouncer" | "snovio";
 /**
- * Default provider order
+ * Default provider order - 2-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)
+ *   - construct: Pattern guessing + MX check (FREE)
+ *
+ * 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)
  *
- * Strategy:
- * 1. construct - FREE pattern guessing with MX check
- * 2. bouncer - SMTP verification of construct results ($0.006/email)
- * 3. ldd - FREE LinkedIn data dump lookup
- * 4. smartprospect - Paid SmartLead lookup ($0.01/email)
- * 5. snovio - Email finder for catch-all domains ($0.02/email)
- * 6. hunter - Hunter.io API ($0.005/email)
- * 7. apollo - FREE Apollo.io lookup
- * 8. dropcontact - Dropcontact API ($0.01/email)
+ * Note: dropcontact available but not in default order (expensive at $0.01)
  */
 export declare const DEFAULT_PROVIDER_ORDER: ProviderName[];
 /**
  * Provider costs in USD per lookup
  *
  * Costs based on 2025 pricing:
- * - Bouncer: $0.006/email at scale (best accuracy 99%+)
- * - Snov.io: $0.02/email (email finding + verification)
- * - Hunter: $0.005/email
- * - SmartProspect: $0.01/email
- * - Dropcontact: $0.01/email
+ * - ldd: FREE (subscription-based)
+ * - smartprospect: FREE (included in SmartLead subscription)
+ * - construct: FREE (pattern guessing + MX check)
+ * - bouncer: $0.006/email (SMTP verification, 99%+ accuracy)
+ * - snovio: $0.02/email (email finding + verification)
+ * - hunter: $0.005/email
+ * - dropcontact: $0.01/email (not in default order)
  */
 export declare const PROVIDER_COSTS: Record<ProviderName, number>;
 /**

package/dist/enrichment/types.js

@@ -8,44 +8,45 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.SMARTPROSPECT_SUB_INDUSTRIES = exports.PROVIDER_COSTS = exports.DEFAULT_PROVIDER_ORDER = void 0;
 /**
- * Default provider order
+ * Default provider order - 2-Phase Strategy
  *
- * Strategy:
- * 1. construct - FREE pattern guessing with MX check
- * 2. bouncer - SMTP verification of construct results ($0.006/email)
- * 3. ldd - FREE LinkedIn data dump lookup
- * 4. smartprospect - Paid SmartLead lookup ($0.01/email)
- * 5. snovio - Email finder for catch-all domains ($0.02/email)
- * 6. hunter - Hunter.io API ($0.005/email)
- * 7. apollo - FREE Apollo.io lookup
- * 8. dropcontact - Dropcontact API ($0.01/email)
+ * 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)
+ *   - construct: Pattern guessing + MX check (FREE)
+ *
+ * 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)
+ *
+ * Note: dropcontact available but not in default order (expensive at $0.01)
  */
 exports.DEFAULT_PROVIDER_ORDER = [
-    "construct",
-    "bouncer",
     "ldd",
     "smartprospect",
+    "construct",
+    "bouncer",
     "snovio",
     "hunter",
-    "apollo",
-    "dropcontact",
 ];
 /**
  * Provider costs in USD per lookup
  *
  * Costs based on 2025 pricing:
- * - Bouncer: $0.006/email at scale (best accuracy 99%+)
- * - Snov.io: $0.02/email (email finding + verification)
- * - Hunter: $0.005/email
- * - SmartProspect: $0.01/email
- * - Dropcontact: $0.01/email
+ * - ldd: FREE (subscription-based)
+ * - smartprospect: FREE (included in SmartLead subscription)
+ * - construct: FREE (pattern guessing + MX check)
+ * - bouncer: $0.006/email (SMTP verification, 99%+ accuracy)
+ * - snovio: $0.02/email (email finding + verification)
+ * - hunter: $0.005/email
+ * - dropcontact: $0.01/email (not in default order)
  */
 exports.PROVIDER_COSTS = {
     construct: 0,
     ldd: 0,
-    smartprospect: 0.01,
+    smartprospect: 0,
     hunter: 0.005,
-    apollo: 0,
     dropcontact: 0.01,
     bouncer: 0.006,
     snovio: 0.02,

package/dist/enrichment/utils/http-retry.d.ts

@@ -0,0 +1,96 @@
+/**
+ * HTTP Retry Utilities
+ *
+ * Shared utilities for HTTP requests with retry logic, rate limit handling,
+ * and exponential backoff. Used across all enrichment providers.
+ */
+/**
+ * Delay execution for specified milliseconds
+ */
+export declare function delay(ms: number): Promise<void>;
+/**
+ * Check if a value is truthy (not null, undefined, or empty string)
+ */
+export declare function truthy(v: unknown): boolean;
+/**
+ * Map common verification status strings to boolean
+ */
+export declare function mapVerifiedStatus(status: string | undefined | null): boolean | undefined;
+/**
+ * Options for fetch with retry
+ */
+export interface FetchWithRetryOptions {
+    /** Number of retries (default: 1) */
+    retries?: number;
+    /** Initial backoff in ms (default: 200) */
+    backoffMs?: number;
+    /** Timeout in ms (default: 30000) */
+    timeoutMs?: number;
+    /** HTTP status codes that should trigger retry (default: [429, 502, 503, 504]) */
+    retryOnStatus?: number[];
+}
+/**
+ * Generic API response type
+ */
+export interface ApiResponse {
+    data?: unknown;
+    result?: unknown;
+    people?: unknown[];
+    matches?: unknown[];
+    emails?: unknown[];
+    success?: boolean;
+    message?: string;
+    [key: string]: unknown;
+}
+/**
+ * HTTP request with retry on rate limit and transient errors
+ *
+ * Features:
+ * - Exponential backoff on rate limit (429)
+ * - Retry on server errors (502, 503, 504)
+ * - Configurable timeout
+ * - Returns typed response
+ *
+ * @example
+ * ```typescript
+ * const response = await fetchWithRetry<MyApiResponse>(
+ *   'https://api.example.com/data',
+ *   {
+ *     method: 'POST',
+ *     headers: { 'Content-Type': 'application/json' },
+ *     body: JSON.stringify({ query: 'test' }),
+ *   },
+ *   { retries: 2, backoffMs: 300 }
+ * );
+ * ```
+ */
+export declare function fetchWithRetry<T = ApiResponse>(url: string, init?: RequestInit, options?: FetchWithRetryOptions): Promise<T>;
+/**
+ * Simpler GET request with retry (no request body)
+ *
+ * @example
+ * ```typescript
+ * const data = await getWithRetry<UserData>(
+ *   `https://api.example.com/users/${id}`,
+ *   { 'Authorization': `Bearer ${token}` }
+ * );
+ * ```
+ */
+export declare function getWithRetry<T = ApiResponse>(url: string, headers?: Record<string, string>, options?: FetchWithRetryOptions): Promise<T>;
+/**
+ * POST request with JSON body and retry
+ *
+ * @example
+ * ```typescript
+ * const result = await postWithRetry<SearchResult>(
+ *   'https://api.example.com/search',
+ *   { query: 'test', limit: 10 },
+ *   { 'X-Api-Key': apiKey }
+ * );
+ * ```
+ */
+export declare function postWithRetry<T = ApiResponse>(url: string, body: Record<string, unknown>, headers?: Record<string, string>, options?: FetchWithRetryOptions): Promise<T>;
+/**
+ * Safe JSON parse with fallback
+ */
+export declare function safeJsonParse<T>(str: string, fallback: T): T;