linkedin-secret-sauce 0.11.0 → 0.11.1

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.11.0",
+  "version": "0.11.1",
   "description": "Private LinkedIn Sales Navigator client with automatic cookie management",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -10,6 +10,30 @@
   "publishConfig": {
     "registry": "https://registry.npmjs.org/"
   },
+  "scripts": {
+    "dev:playground": "pnpm -C apps/playground dev",
+    "search": "node scripts/rg-fast.mjs",
+    "rg:fast": "node scripts/rg-fast.mjs",
+    "build": "tsc -p tsconfig.json",
+    "typecheck": "tsc --noEmit",
+    "typecheck:playground": "pnpm -C apps/playground typecheck",
+    "typecheck:all": "pnpm typecheck && pnpm typecheck:playground",
+    "lint": "eslint \"src/**/*.ts\" --max-warnings=0",
+    "lint:playground": "eslint \"apps/playground/src/**/*.{ts,tsx}\" \"apps/playground/server/**/*.ts\" --max-warnings=0",
+    "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": "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",
+    "release:major": "npm version major && git push --follow-tags"
+  },
   "keywords": [
     "linkedin",
     "sales-navigator",
@@ -28,35 +52,19 @@
   "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"
-  },
-  "scripts": {
-    "dev:playground": "pnpm -C apps/playground dev",
-    "search": "node scripts/rg-fast.mjs",
-    "rg:fast": "node scripts/rg-fast.mjs",
-    "build": "tsc -p tsconfig.json",
-    "typecheck": "tsc --noEmit",
-    "typecheck:playground": "pnpm -C apps/playground typecheck",
-    "typecheck:all": "pnpm typecheck && pnpm typecheck:playground",
-    "lint": "eslint \"src/**/*.ts\" --max-warnings=0",
-    "lint:playground": "eslint \"apps/playground/src/**/*.{ts,tsx}\" \"apps/playground/server/**/*.ts\" --max-warnings=0",
-    "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",
-    "test": "vitest run",
-    "release:patch": "npm version patch && git push --follow-tags",
-    "release:minor": "npm version minor && git push --follow-tags",
-    "release:major": "npm version major && git push --follow-tags"
   }
-}
+}