linkedin-secret-sauce 0.10.1 → 0.11.1

package/dist/index.d.ts

@@ -1,18 +1,208 @@
+/**
+ * LinkedIn Secret Sauce
+ *
+ * A complete LinkedIn Sales Navigator client + Email Enrichment library.
+ *
+ * ## Two Main Modules
+ *
+ * ### 1. LinkedIn API
+ * Server-side LinkedIn Sales Navigator client with automatic cookie management,
+ * retries, caching, and parsing.
+ *
+ * ```typescript
+ * import { initializeLinkedInClient, searchSalesLeads, getProfileByVanity } from 'linkedin-secret-sauce';
+ *
+ * initializeLinkedInClient({
+ *   cosiallApiUrl: process.env.COSIALL_API_URL,
+ *   cosiallApiKey: process.env.COSIALL_API_KEY,
+ * });
+ *
+ * const profile = await getProfileByVanity('john-doe');
+ * const leads = await searchSalesLeads('cto fintech', { count: 25 });
+ * ```
+ *
+ * ### 2. Email Enrichment
+ * Find business emails using multiple providers with waterfall/parallel strategies.
+ *
+ * ```typescript
+ * import { createEnrichmentClient } from 'linkedin-secret-sauce';
+ *
+ * const enrichment = createEnrichmentClient({
+ *   providers: {
+ *     hunter: { apiKey: process.env.HUNTER_API_KEY },
+ *     bouncer: { apiKey: process.env.BOUNCER_API_KEY },
+ *   },
+ * });
+ *
+ * const result = await enrichment.enrich({
+ *   firstName: 'John',
+ *   lastName: 'Doe',
+ *   domain: 'acme.com',
+ * });
+ * console.log(result.business_email); // john.doe@acme.com
+ * ```
+ *
+ * @packageDocumentation
+ */
 export { initializeLinkedInClient, getConfig } from "./config";
 export type { LinkedInClientConfig } from "./config";
+export * from "./linkedin-api";
+export * from "./types";
+export type { LinkedInTenure, LinkedInPosition, LinkedInSpotlightBadge, SalesLeadSearchResult, } from "./types";
 export { LinkedInClientError } from "./utils/errors";
 export * from "./cosiall-client";
 export * from "./cookie-pool";
 export { parseFullProfile } from "./parsers/profile-parser";
 export { parseSalesSearchResults } from "./parsers/search-parser";
-export * from "./linkedin-api";
-export * from "./types";
-export type { LinkedInTenure, LinkedInPosition, LinkedInSpotlightBadge, SalesLeadSearchResult, } from "./types";
 export * from "./utils/metrics";
 export { getRequestHistory, clearRequestHistory, } from "./utils/request-history";
 export type { RequestHistoryEntry } from "./utils/request-history";
 export * from "./constants";
+/**
+ * Create an enrichment client for finding business emails
+ *
+ * @example
+ * ```typescript
+ * const enrichment = createEnrichmentClient({
+ *   providers: {
+ *     construct: {},  // FREE pattern matching
+ *     hunter: { apiKey: 'xxx' },
+ *     bouncer: { apiKey: 'xxx' },
+ *   },
+ *   onCost: (provider, cost) => console.log(`${provider}: $${cost}`),
+ * });
+ *
+ * const result = await enrichment.enrich({
+ *   firstName: 'John',
+ *   lastName: 'Doe',
+ *   domain: 'acme.com',
+ * });
+ * ```
+ */
 export { createEnrichmentClient } from "./enrichment";
-export type { CanonicalEmail, EnrichmentCandidate, ProviderResult, ProviderFunc, ProviderName, EnrichmentClientConfig, EnrichmentClient, ProvidersConfig, EnrichmentOptions, BatchEnrichmentOptions, HunterConfig, ApolloConfig, SmartProspectConfig, LddConfig, DropcontactConfig, ConstructConfig, CacheAdapter, CostCallback, EnrichmentLogger, VerificationResult, SmartProspectContact, SmartProspectSearchFilters, LddProfileData, LddApiResponse, } from "./enrichment";
-export { isPersonalEmail, isBusinessEmail, isPersonalDomain, isDisposableEmail, isDisposableDomain, isValidEmailSyntax, isRoleAccount, verifyEmailMx, PERSONAL_DOMAINS, DISPOSABLE_DOMAINS, DEFAULT_PROVIDER_ORDER, PROVIDER_COSTS, getSmartLeadToken, getSmartLeadUser, clearSmartLeadToken, clearAllSmartLeadTokens, getSmartLeadTokenCacheStats, } from "./enrichment";
-export type { SmartLeadCredentials, SmartLeadAuthConfig, SmartLeadUser, SmartLeadLoginResponse, } from "./enrichment";
+export type { 
+/** Result returned by enrichment operations */
+CanonicalEmail, 
+/** Input candidate for email lookup */
+EnrichmentCandidate, 
+/** Raw provider result */
+ProviderResult, 
+/** Provider function signature */
+ProviderFunc, 
+/** Supported provider names */
+ProviderName, 
+/** Full client configuration */
+EnrichmentClientConfig, 
+/** Enrichment client interface */
+EnrichmentClient, 
+/** Provider configuration map */
+ProvidersConfig, 
+/** Enrichment options */
+EnrichmentOptions, 
+/** Batch processing options */
+BatchEnrichmentOptions, 
+/** Hunter.io configuration */
+HunterConfig, 
+/** SmartProspect/SmartLead configuration */
+SmartProspectConfig, 
+/** LinkedIn Data Dump configuration */
+LddConfig, 
+/** Dropcontact configuration */
+DropcontactConfig, 
+/** Construct provider configuration */
+ConstructConfig, 
+/** Cache adapter interface */
+CacheAdapter, 
+/** Cost tracking callback */
+CostCallback, 
+/** Logger interface */
+EnrichmentLogger, 
+/** Email verification result */
+VerificationResult, 
+/** SmartProspect contact */
+SmartProspectContact, 
+/** SmartProspect search filters */
+SmartProspectSearchFilters, 
+/** LDD profile data */
+LddProfileData, 
+/** LDD API response */
+LddApiResponse, } from "./enrichment";
+export { 
+/**
+ * Check if email is from a personal domain (Gmail, Yahoo, etc.)
+ * @example isPersonalEmail('john@gmail.com') // true
+ */
+isPersonalEmail, 
+/**
+ * Check if email is from a business domain
+ * @example isBusinessEmail('john@acme.com') // true
+ */
+isBusinessEmail, 
+/**
+ * Check if domain is a personal email provider
+ * @example isPersonalDomain('gmail.com') // true
+ */
+isPersonalDomain, 
+/**
+ * Check if email is from a disposable/temporary email service
+ * @example isDisposableEmail('test@mailinator.com') // true
+ */
+isDisposableEmail, 
+/**
+ * Check if domain is a disposable email provider
+ * @example isDisposableDomain('guerrillamail.com') // true
+ */
+isDisposableDomain, 
+/**
+ * Validate email syntax
+ * @example isValidEmailSyntax('john@example.com') // true
+ */
+isValidEmailSyntax, 
+/**
+ * Check if email is a role account (info@, support@, etc.)
+ * @example isRoleAccount('info@company.com') // true
+ */
+isRoleAccount, 
+/**
+ * Verify email via MX record lookup
+ */
+verifyEmailMx, 
+/** Set of known personal email domains */
+PERSONAL_DOMAINS, 
+/** Set of known disposable email domains */
+DISPOSABLE_DOMAINS, 
+/** Default provider execution order */
+DEFAULT_PROVIDER_ORDER, 
+/** Cost per lookup by provider (USD) */
+PROVIDER_COSTS, } from "./enrichment";
+export { 
+/**
+ * Get JWT token for SmartLead API (cached, auto-refreshes)
+ * @example const token = await getSmartLeadToken({ credentials: { email, password } });
+ */
+getSmartLeadToken, 
+/**
+ * Get SmartLead user info from cached login
+ */
+getSmartLeadUser, 
+/**
+ * Clear cached token for an email (e.g., on 401 error)
+ */
+clearSmartLeadToken, 
+/**
+ * Clear all cached SmartLead tokens
+ */
+clearAllSmartLeadTokens, 
+/**
+ * Get token cache statistics for debugging
+ */
+getSmartLeadTokenCacheStats, } from "./enrichment";
+export type { 
+/** SmartLead login credentials */
+SmartLeadCredentials, 
+/** SmartLead authentication configuration */
+SmartLeadAuthConfig, 
+/** SmartLead user info */
+SmartLeadUser, 
+/** SmartLead login response */
+SmartLeadLoginResponse, } from "./enrichment";

package/dist/index.js

@@ -1,4 +1,50 @@
 "use strict";
+/**
+ * LinkedIn Secret Sauce
+ *
+ * A complete LinkedIn Sales Navigator client + Email Enrichment library.
+ *
+ * ## Two Main Modules
+ *
+ * ### 1. LinkedIn API
+ * Server-side LinkedIn Sales Navigator client with automatic cookie management,
+ * retries, caching, and parsing.
+ *
+ * ```typescript
+ * import { initializeLinkedInClient, searchSalesLeads, getProfileByVanity } from 'linkedin-secret-sauce';
+ *
+ * initializeLinkedInClient({
+ *   cosiallApiUrl: process.env.COSIALL_API_URL,
+ *   cosiallApiKey: process.env.COSIALL_API_KEY,
+ * });
+ *
+ * const profile = await getProfileByVanity('john-doe');
+ * const leads = await searchSalesLeads('cto fintech', { count: 25 });
+ * ```
+ *
+ * ### 2. Email Enrichment
+ * Find business emails using multiple providers with waterfall/parallel strategies.
+ *
+ * ```typescript
+ * import { createEnrichmentClient } from 'linkedin-secret-sauce';
+ *
+ * const enrichment = createEnrichmentClient({
+ *   providers: {
+ *     hunter: { apiKey: process.env.HUNTER_API_KEY },
+ *     bouncer: { apiKey: process.env.BOUNCER_API_KEY },
+ *   },
+ * });
+ *
+ * const result = await enrichment.enrich({
+ *   firstName: 'John',
+ *   lastName: 'Doe',
+ *   domain: 'acme.com',
+ * });
+ * console.log(result.business_email); // john.doe@acme.com
+ * ```
+ *
+ * @packageDocumentation
+ */
 var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
     if (k2 === undefined) k2 = k;
     var desc = Object.getOwnPropertyDescriptor(m, k);
@@ -15,46 +61,147 @@ var __exportStar = (this && this.__exportStar) || function(m, exports) {
 };
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.getSmartLeadTokenCacheStats = exports.clearAllSmartLeadTokens = exports.clearSmartLeadToken = exports.getSmartLeadUser = exports.getSmartLeadToken = exports.PROVIDER_COSTS = exports.DEFAULT_PROVIDER_ORDER = exports.DISPOSABLE_DOMAINS = exports.PERSONAL_DOMAINS = exports.verifyEmailMx = exports.isRoleAccount = exports.isValidEmailSyntax = exports.isDisposableDomain = exports.isDisposableEmail = exports.isPersonalDomain = exports.isBusinessEmail = exports.isPersonalEmail = exports.createEnrichmentClient = exports.clearRequestHistory = exports.getRequestHistory = exports.parseSalesSearchResults = exports.parseFullProfile = exports.LinkedInClientError = exports.getConfig = exports.initializeLinkedInClient = void 0;
+// =============================================================================
+// LinkedIn API - Configuration
+// =============================================================================
 var config_1 = require("./config");
 Object.defineProperty(exports, "initializeLinkedInClient", { enumerable: true, get: function () { return config_1.initializeLinkedInClient; } });
 Object.defineProperty(exports, "getConfig", { enumerable: true, get: function () { return config_1.getConfig; } });
+// =============================================================================
+// LinkedIn API - Core Functions
+// =============================================================================
+__exportStar(require("./linkedin-api"), exports);
+// =============================================================================
+// LinkedIn API - Types
+// =============================================================================
+__exportStar(require("./types"), exports);
+// =============================================================================
+// LinkedIn API - Errors
+// =============================================================================
 var errors_1 = require("./utils/errors");
 Object.defineProperty(exports, "LinkedInClientError", { enumerable: true, get: function () { return errors_1.LinkedInClientError; } });
+// =============================================================================
+// LinkedIn API - Cookie Management
+// =============================================================================
 __exportStar(require("./cosiall-client"), exports);
 __exportStar(require("./cookie-pool"), exports);
+// =============================================================================
+// LinkedIn API - Parsers
+// =============================================================================
 var profile_parser_1 = require("./parsers/profile-parser");
 Object.defineProperty(exports, "parseFullProfile", { enumerable: true, get: function () { return profile_parser_1.parseFullProfile; } });
 var search_parser_1 = require("./parsers/search-parser");
 Object.defineProperty(exports, "parseSalesSearchResults", { enumerable: true, get: function () { return search_parser_1.parseSalesSearchResults; } });
-__exportStar(require("./linkedin-api"), exports);
-__exportStar(require("./types"), exports);
+// =============================================================================
+// LinkedIn API - Metrics & Monitoring
+// =============================================================================
 __exportStar(require("./utils/metrics"), exports);
 var request_history_1 = require("./utils/request-history");
 Object.defineProperty(exports, "getRequestHistory", { enumerable: true, get: function () { return request_history_1.getRequestHistory; } });
 Object.defineProperty(exports, "clearRequestHistory", { enumerable: true, get: function () { return request_history_1.clearRequestHistory; } });
+// =============================================================================
+// LinkedIn API - Constants
+// =============================================================================
 __exportStar(require("./constants"), exports);
-// Email Enrichment Module
+// =============================================================================
+// Email Enrichment - Client
+// =============================================================================
+/**
+ * Create an enrichment client for finding business emails
+ *
+ * @example
+ * ```typescript
+ * const enrichment = createEnrichmentClient({
+ *   providers: {
+ *     construct: {},  // FREE pattern matching
+ *     hunter: { apiKey: 'xxx' },
+ *     bouncer: { apiKey: 'xxx' },
+ *   },
+ *   onCost: (provider, cost) => console.log(`${provider}: $${cost}`),
+ * });
+ *
+ * const result = await enrichment.enrich({
+ *   firstName: 'John',
+ *   lastName: 'Doe',
+ *   domain: 'acme.com',
+ * });
+ * ```
+ */
 var enrichment_1 = require("./enrichment");
 Object.defineProperty(exports, "createEnrichmentClient", { enumerable: true, get: function () { return enrichment_1.createEnrichmentClient; } });
+// =============================================================================
+// Email Enrichment - Utilities
+// =============================================================================
 var enrichment_2 = require("./enrichment");
-// Utilities
+/**
+ * Check if email is from a personal domain (Gmail, Yahoo, etc.)
+ * @example isPersonalEmail('john@gmail.com') // true
+ */
 Object.defineProperty(exports, "isPersonalEmail", { enumerable: true, get: function () { return enrichment_2.isPersonalEmail; } });
+/**
+ * Check if email is from a business domain
+ * @example isBusinessEmail('john@acme.com') // true
+ */
 Object.defineProperty(exports, "isBusinessEmail", { enumerable: true, get: function () { return enrichment_2.isBusinessEmail; } });
+/**
+ * Check if domain is a personal email provider
+ * @example isPersonalDomain('gmail.com') // true
+ */
 Object.defineProperty(exports, "isPersonalDomain", { enumerable: true, get: function () { return enrichment_2.isPersonalDomain; } });
+/**
+ * Check if email is from a disposable/temporary email service
+ * @example isDisposableEmail('test@mailinator.com') // true
+ */
 Object.defineProperty(exports, "isDisposableEmail", { enumerable: true, get: function () { return enrichment_2.isDisposableEmail; } });
+/**
+ * Check if domain is a disposable email provider
+ * @example isDisposableDomain('guerrillamail.com') // true
+ */
 Object.defineProperty(exports, "isDisposableDomain", { enumerable: true, get: function () { return enrichment_2.isDisposableDomain; } });
+/**
+ * Validate email syntax
+ * @example isValidEmailSyntax('john@example.com') // true
+ */
 Object.defineProperty(exports, "isValidEmailSyntax", { enumerable: true, get: function () { return enrichment_2.isValidEmailSyntax; } });
+/**
+ * Check if email is a role account (info@, support@, etc.)
+ * @example isRoleAccount('info@company.com') // true
+ */
 Object.defineProperty(exports, "isRoleAccount", { enumerable: true, get: function () { return enrichment_2.isRoleAccount; } });
-// Verification
+/**
+ * Verify email via MX record lookup
+ */
 Object.defineProperty(exports, "verifyEmailMx", { enumerable: true, get: function () { return enrichment_2.verifyEmailMx; } });
-// Constants
+/** Set of known personal email domains */
 Object.defineProperty(exports, "PERSONAL_DOMAINS", { enumerable: true, get: function () { return enrichment_2.PERSONAL_DOMAINS; } });
+/** Set of known disposable email domains */
 Object.defineProperty(exports, "DISPOSABLE_DOMAINS", { enumerable: true, get: function () { return enrichment_2.DISPOSABLE_DOMAINS; } });
+/** Default provider execution order */
 Object.defineProperty(exports, "DEFAULT_PROVIDER_ORDER", { enumerable: true, get: function () { return enrichment_2.DEFAULT_PROVIDER_ORDER; } });
+/** Cost per lookup by provider (USD) */
 Object.defineProperty(exports, "PROVIDER_COSTS", { enumerable: true, get: function () { return enrichment_2.PROVIDER_COSTS; } });
-// SmartLead Auth
-Object.defineProperty(exports, "getSmartLeadToken", { enumerable: true, get: function () { return enrichment_2.getSmartLeadToken; } });
-Object.defineProperty(exports, "getSmartLeadUser", { enumerable: true, get: function () { return enrichment_2.getSmartLeadUser; } });
-Object.defineProperty(exports, "clearSmartLeadToken", { enumerable: true, get: function () { return enrichment_2.clearSmartLeadToken; } });
-Object.defineProperty(exports, "clearAllSmartLeadTokens", { enumerable: true, get: function () { return enrichment_2.clearAllSmartLeadTokens; } });
-Object.defineProperty(exports, "getSmartLeadTokenCacheStats", { enumerable: true, get: function () { return enrichment_2.getSmartLeadTokenCacheStats; } });
+// =============================================================================
+// Email Enrichment - SmartLead Authentication
+// =============================================================================
+var enrichment_3 = require("./enrichment");
+/**
+ * Get JWT token for SmartLead API (cached, auto-refreshes)
+ * @example const token = await getSmartLeadToken({ credentials: { email, password } });
+ */
+Object.defineProperty(exports, "getSmartLeadToken", { enumerable: true, get: function () { return enrichment_3.getSmartLeadToken; } });
+/**
+ * Get SmartLead user info from cached login
+ */
+Object.defineProperty(exports, "getSmartLeadUser", { enumerable: true, get: function () { return enrichment_3.getSmartLeadUser; } });
+/**
+ * Clear cached token for an email (e.g., on 401 error)
+ */
+Object.defineProperty(exports, "clearSmartLeadToken", { enumerable: true, get: function () { return enrichment_3.clearSmartLeadToken; } });
+/**
+ * Clear all cached SmartLead tokens
+ */
+Object.defineProperty(exports, "clearAllSmartLeadTokens", { enumerable: true, get: function () { return enrichment_3.clearAllSmartLeadTokens; } });
+/**
+ * Get token cache statistics for debugging
+ */
+Object.defineProperty(exports, "getSmartLeadTokenCacheStats", { enumerable: true, get: function () { return enrichment_3.getSmartLeadTokenCacheStats; } });

package/dist/parsers/search-parser.js

@@ -9,10 +9,14 @@ function parseSalesSearchResults(rawResponse) {
         : [];
     const results = [];
     for (const el of elements) {
-        const name = [el?.firstName, el?.lastName].filter(Boolean).join(" ").trim() ||
-            undefined;
+        const firstName = (0, json_sanitizer_1.sanitizeForJson)(el?.firstName) || undefined;
+        const lastName = (0, json_sanitizer_1.sanitizeForJson)(el?.lastName) || undefined;
+        const fullName = [firstName, lastName].filter(Boolean).join(" ").trim() || undefined;
         const res = {
-            name: (0, json_sanitizer_1.sanitizeForJson)(name),
+            firstName,
+            lastName,
+            fullName,
+            name: fullName, // Backward compatible
             headline: (0, json_sanitizer_1.sanitizeForJson)((el?.summary || "").split("\n")[0]?.slice(0, 180)),
             salesProfileUrn: el?.entityUrn,
             objectUrn: el?.objectUrn,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "linkedin-secret-sauce",
-  "version": "0.10.1",
+  "version": "0.11.1",
   "description": "Private LinkedIn Sales Navigator client with automatic cookie management",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -23,8 +23,12 @@
     "lint:all": "eslint \"src/**/*.ts\" \"apps/playground/src/**/*.{ts,tsx}\" \"apps/playground/server/**/*.ts\" --max-warnings=0",
     "lint:fix": "eslint \"src/**/*.ts\" \"apps/playground/src/**/*.{ts,tsx}\" \"apps/playground/server/**/*.ts\" --fix",
     "check": "pnpm typecheck:all && pnpm lint:all",
-    "dev": "tsc -w -p tsconfig.json",
+    "dev": "pnpm dev:playground",
+    "dev:watch": "tsc -w -p tsconfig.json",
     "test": "vitest run",
+    "docs": "typedoc",
+    "docs:netlify": "rm -rf docs/api && typedoc && echo 'Build complete'",
+    "docs:watch": "typedoc --watch",
     "prepublishOnly": "npm run build",
     "release:patch": "npm version patch && git push --follow-tags",
     "release:minor": "npm version minor && git push --follow-tags",
@@ -48,15 +52,18 @@
   "bugs": {
     "url": "https://github.com/enerage/LinkedInSecretSauce/issues"
   },
-  "homepage": "https://github.com/enerage/LinkedInSecretSauce#readme",
+  "homepage": "https://enerage.github.io/LinkedInSecretSauce/",
   "devDependencies": {
     "@commitlint/cli": "^19.4.0",
     "@commitlint/config-conventional": "^19.4.0",
     "@types/node": "^20.11.0",
     "@typescript-eslint/eslint-plugin": "^8.9.0",
     "@typescript-eslint/parser": "^8.9.0",
+    "concurrently": "^9.2.1",
     "eslint": "^9.12.0",
     "husky": "^9.0.11",
+    "typedoc": "^0.28.15",
+    "typedoc-plugin-markdown": "^4.9.0",
     "typescript": "^5.9.3",
     "vitest": "^1.6.0"
   }