linkedin-secret-sauce 0.3.29 → 0.5.0

package/dist/linkedin-api.js

@@ -41,6 +41,7 @@ exports.getProfilesBatch = getProfilesBatch;
 exports.resolveCompanyUniversalName = resolveCompanyUniversalName;
 exports.getCompanyById = getCompanyById;
 exports.getCompanyByUrl = getCompanyByUrl;
+exports.getCompaniesBatch = getCompaniesBatch;
 exports.typeahead = typeahead;
 exports.getYearsAtCompanyOptions = getYearsAtCompanyOptions;
 exports.getYearsInPositionOptions = getYearsInPositionOptions;
@@ -56,8 +57,8 @@ const metrics_1 = require("./utils/metrics");
 const logger_1 = require("./utils/logger");
 const errors_1 = require("./utils/errors");
 const constants_1 = require("./constants");
-const LINKEDIN_API_BASE = 'https://www.linkedin.com/voyager/api';
-const SALES_NAV_BASE = 'https://www.linkedin.com/sales-api';
+const LINKEDIN_API_BASE = "https://www.linkedin.com/voyager/api";
+const SALES_NAV_BASE = "https://www.linkedin.com/sales-api";
 // In-memory caches (per-process)
 const profileCacheByVanity = new Map();
 const profileCacheByUrn = new Map();
@@ -77,23 +78,41 @@ function getCached(map, key, ttl) {
     }
     return entry.data;
 }
+/**
+ * Fetches a LinkedIn profile by vanity URL (public identifier).
+ * Results are cached for the configured TTL (default: 15 minutes).
+ *
+ * @param vanity - The public identifier from LinkedIn URL (e.g., "johndoe" from linkedin.com/in/johndoe)
+ * @returns Parsed LinkedInProfile with positions, education, skills, and metadata
+ * @throws LinkedInClientError with code NOT_FOUND if profile doesn't exist
+ * @throws LinkedInClientError with code PARSE_ERROR if response cannot be parsed
+ *
+ * @example
+ * ```typescript
+ * const profile = await getProfileByVanity('johndoe');
+ * console.log(profile.firstName, profile.headline);
+ * ```
+ */
 async function getProfileByVanity(vanity) {
     const cfg = (0, config_1.getConfig)();
-    const key = String(vanity || '').toLowerCase();
+    const key = String(vanity || "").toLowerCase();
     try {
-        (0, logger_1.log)('info', 'api.start', { operation: 'getProfileByVanity', selector: key });
+        (0, logger_1.log)("info", "api.start", {
+            operation: "getProfileByVanity",
+            selector: key,
+        });
     }
     catch { }
     // Cache
     const cached = getCached(profileCacheByVanity, key, cfg.profileCacheTtl);
     if (cached) {
-        (0, metrics_1.incrementMetric)('profileCacheHits');
+        (0, metrics_1.incrementMetric)("profileCacheHits");
         return cached;
     }
     // In-flight dedupe
     const inflight = inflightByVanity.get(key);
     if (inflight) {
-        (0, metrics_1.incrementMetric)('inflightDedupeHits');
+        (0, metrics_1.incrementMetric)("inflightDedupeHits");
         return inflight;
     }
     const url = `${LINKEDIN_API_BASE}/identity/dash/profiles?q=memberIdentity&memberIdentity=${encodeURIComponent(vanity)}&decorationId=com.linkedin.voyager.dash.deco.identity.profile.FullProfileWithEntities-35`;
@@ -101,16 +120,20 @@ async function getProfileByVanity(vanity) {
         try {
             let raw;
             try {
-                raw = await (0, http_client_1.executeLinkedInRequest)({ url }, 'getProfileByVanity');
+                raw = await (0, http_client_1.executeLinkedInRequest)({ url }, "getProfileByVanity");
             }
             catch (e) {
                 const status = e?.status ?? 0;
                 if (status === 404) {
                     try {
-                        (0, logger_1.log)('warn', 'api.notFound', { operation: 'getProfileByVanity', selector: key, status });
+                        (0, logger_1.log)("warn", "api.notFound", {
+                            operation: "getProfileByVanity",
+                            selector: key,
+                            status,
+                        });
                     }
                     catch { }
-                    throw new errors_1.LinkedInClientError('Profile not found', errors_1.ERROR_CODES.NOT_FOUND, 404);
+                    throw new errors_1.LinkedInClientError("Profile not found", errors_1.ERROR_CODES.NOT_FOUND, 404);
                 }
                 throw e;
             }
@@ -120,15 +143,21 @@ async function getProfileByVanity(vanity) {
             }
             catch {
                 try {
-                    (0, logger_1.log)('error', 'api.parseError', { operation: 'getProfileByVanity', selector: key });
+                    (0, logger_1.log)("error", "api.parseError", {
+                        operation: "getProfileByVanity",
+                        selector: key,
+                    });
                 }
                 catch { }
-                throw new errors_1.LinkedInClientError('Failed to parse profile', errors_1.ERROR_CODES.PARSE_ERROR, 500);
+                throw new errors_1.LinkedInClientError("Failed to parse profile", errors_1.ERROR_CODES.PARSE_ERROR, 500);
             }
             profileCacheByVanity.set(key, { data: prof, ts: Date.now() });
-            (0, metrics_1.incrementMetric)('profileFetches');
+            (0, metrics_1.incrementMetric)("profileFetches");
             try {
-                (0, logger_1.log)('info', 'api.ok', { operation: 'getProfileByVanity', selector: key });
+                (0, logger_1.log)("info", "api.ok", {
+                    operation: "getProfileByVanity",
+                    selector: key,
+                });
             }
             catch { }
             return prof;
@@ -140,36 +169,69 @@ async function getProfileByVanity(vanity) {
     inflightByVanity.set(key, p);
     return p;
 }
+/**
+ * Fetches a LinkedIn profile by FSD key or URN.
+ * Accepts multiple input formats and normalizes them.
+ * Results are cached for the configured TTL (default: 15 minutes).
+ *
+ * @param fsdKey - Profile identifier in any of these formats:
+ *   - Bare key: "ABC123xyz"
+ *   - FSD profile URN: "urn:li:fsd_profile:ABC123xyz"
+ *   - Sales profile URN: "urn:li:fs_salesProfile:(ABC123xyz,NAME_SEARCH,abc)"
+ * @returns Parsed LinkedInProfile with positions, education, skills, and metadata
+ * @throws LinkedInClientError with code INVALID_INPUT if URN format is invalid
+ * @throws LinkedInClientError with code NOT_FOUND if profile doesn't exist
+ * @throws LinkedInClientError with code PARSE_ERROR if response cannot be parsed
+ *
+ * @example
+ * ```typescript
+ * // By bare key
+ * const profile = await getProfileByUrn('ABC123xyz');
+ *
+ * // By URN from search results
+ * const profile = await getProfileByUrn(searchResult.salesProfileUrn);
+ * ```
+ */
 async function getProfileByUrn(fsdKey) {
     const cfg = (0, config_1.getConfig)();
     // Normalize input: accept bare KEY or URN variants and extract KEY
-    const input = String(fsdKey || '').trim();
+    const input = String(fsdKey || "").trim();
     const keyMatch = input.match(/^urn:li:fsd_profile:([^\s/]+)$/i)?.[1] ||
         input.match(/^urn:li:fs_salesProfile:\(([^,\s)]+)/i)?.[1] ||
         (input.match(/^[A-Za-z0-9_-]+$/) ? input : null);
     if (!keyMatch) {
-        throw new errors_1.LinkedInClientError('Invalid URN or key', errors_1.ERROR_CODES.INVALID_INPUT, 400);
+        throw new errors_1.LinkedInClientError("Invalid URN or key", errors_1.ERROR_CODES.INVALID_INPUT, 400);
     }
     const cacheKey = keyMatch; // Preserve case for FSD keys (case-sensitive)
     try {
-        (0, logger_1.log)('info', 'api.start', { operation: 'getProfileByUrn', selector: keyMatch });
+        (0, logger_1.log)("info", "api.start", {
+            operation: "getProfileByUrn",
+            selector: keyMatch,
+        });
     }
     catch { }
     const cachedUrn = getCached(profileCacheByUrn, cacheKey, cfg.profileCacheTtl);
     if (cachedUrn) {
-        (0, metrics_1.incrementMetric)('profileCacheHits');
+        (0, metrics_1.incrementMetric)("profileCacheHits");
         return cachedUrn;
     }
     const url = `${LINKEDIN_API_BASE}/identity/dash/profiles?q=memberIdentity&memberIdentity=${encodeURIComponent(keyMatch)}&decorationId=com.linkedin.voyager.dash.deco.identity.profile.FullProfileWithEntities-35`;
     try {
-        (0, logger_1.log)('debug', 'api.requestUrl', { operation: 'getProfileByUrn', url, fsdKey: keyMatch });
+        (0, logger_1.log)("debug", "api.requestUrl", {
+            operation: "getProfileByUrn",
+            url,
+            fsdKey: keyMatch,
+        });
     }
     catch { }
     let raw;
     try {
-        raw = await (0, http_client_1.executeLinkedInRequest)({ url }, 'getProfileByUrn');
+        raw = await (0, http_client_1.executeLinkedInRequest)({ url }, "getProfileByUrn");
         try {
-            (0, logger_1.log)('debug', 'api.rawResponse', { operation: 'getProfileByUrn', responseSize: JSON.stringify(raw).length });
+            (0, logger_1.log)("debug", "api.rawResponse", {
+                operation: "getProfileByUrn",
+                responseSize: JSON.stringify(raw).length,
+            });
         }
         catch { }
     }
@@ -177,10 +239,14 @@ async function getProfileByUrn(fsdKey) {
         const status = e?.status ?? 0;
         if (status === 404) {
             try {
-                (0, logger_1.log)('warn', 'api.notFound', { operation: 'getProfileByUrn', selector: cacheKey, status });
+                (0, logger_1.log)("warn", "api.notFound", {
+                    operation: "getProfileByUrn",
+                    selector: cacheKey,
+                    status,
+                });
             }
             catch { }
-            throw new errors_1.LinkedInClientError('Profile not found', errors_1.ERROR_CODES.NOT_FOUND, 404);
+            throw new errors_1.LinkedInClientError("Profile not found", errors_1.ERROR_CODES.NOT_FOUND, 404);
         }
         throw e;
     }
@@ -188,31 +254,47 @@ async function getProfileByUrn(fsdKey) {
     // BUG FIX: LinkedIn API returns multiple profiles (requested profile + connections/colleagues)
     // The correct profile is referenced in data.*elements[0] - we must match against this URN
     const rr = raw;
-    const included = Array.isArray(rr?.included) ? rr.included : [];
+    const included = Array.isArray(rr?.included)
+        ? rr.included
+        : [];
     // Get the primary profile URN from data.*elements[0]
     const dataObj = rr?.data;
-    const elementsArray = dataObj?.['*elements'];
+    const elementsArray = dataObj?.["*elements"];
     const requestedProfileUrn = elementsArray?.[0];
     // Find the profile in included[] that matches the requested URN
     const identityObj = requestedProfileUrn
         ? included.find((it) => {
             const rec = it;
-            const isProfile = String(rec?.$type || '').includes('identity.profile.Profile');
+            const isProfile = String(rec?.$type || "").includes("identity.profile.Profile");
             if (!isProfile)
                 return false;
             // Match the entityUrn against the requested profile URN from data.*elements[0]
             return rec.entityUrn === requestedProfileUrn;
         })
         : undefined;
-    const publicIdentifier = identityObj?.publicIdentifier || '';
+    // Validate that requested profile was found in response
+    if (requestedProfileUrn && !identityObj) {
+        const profilesInResponse = included.filter((it) => String(it?.$type || "").includes("identity.profile.Profile")).length;
+        try {
+            (0, logger_1.log)("error", "api.profileNotFoundInResponse", {
+                operation: "getProfileByUrn",
+                requestedUrn: requestedProfileUrn,
+                profilesInResponse,
+                selector: cacheKey,
+            });
+        }
+        catch { }
+        throw new errors_1.LinkedInClientError("Requested profile not found in API response", errors_1.ERROR_CODES.PARSE_ERROR, 500);
+    }
+    const publicIdentifier = identityObj?.publicIdentifier || "";
     try {
-        (0, logger_1.log)('debug', 'api.extractedIdentity', {
-            operation: 'getProfileByUrn',
+        (0, logger_1.log)("debug", "api.extractedIdentity", {
+            operation: "getProfileByUrn",
             publicIdentifier,
             firstName: identityObj?.firstName,
             lastName: identityObj?.lastName,
             objectUrn: identityObj?.objectUrn,
-            profilesInResponse: included.filter(it => String(it?.$type || '').includes('identity.profile.Profile')).length
+            profilesInResponse: included.filter((it) => String(it?.$type || "").includes("identity.profile.Profile")).length,
         });
     }
     catch { }
@@ -221,40 +303,100 @@ async function getProfileByUrn(fsdKey) {
         // Pass publicIdentifier to parser so it can validate profile selection (same logic as getProfileByVanity)
         prof = (0, profile_parser_1.parseFullProfile)(raw, publicIdentifier);
         try {
-            (0, logger_1.log)('debug', 'api.parsedProfile', { operation: 'getProfileByUrn', firstName: prof.firstName, lastName: prof.lastName, vanity: prof.vanity });
+            (0, logger_1.log)("debug", "api.parsedProfile", {
+                operation: "getProfileByUrn",
+                firstName: prof.firstName,
+                lastName: prof.lastName,
+                vanity: prof.vanity,
+            });
         }
         catch { }
     }
     catch {
         try {
-            (0, logger_1.log)('error', 'api.parseError', { operation: 'getProfileByUrn', selector: cacheKey });
+            (0, logger_1.log)("error", "api.parseError", {
+                operation: "getProfileByUrn",
+                selector: cacheKey,
+            });
         }
         catch { }
-        throw new errors_1.LinkedInClientError('Failed to parse profile', errors_1.ERROR_CODES.PARSE_ERROR, 500);
+        throw new errors_1.LinkedInClientError("Failed to parse profile", errors_1.ERROR_CODES.PARSE_ERROR, 500);
     }
     profileCacheByUrn.set(cacheKey, { data: prof, ts: Date.now() });
-    (0, metrics_1.incrementMetric)('profileFetches');
+    (0, metrics_1.incrementMetric)("profileFetches");
     try {
-        (0, logger_1.log)('info', 'api.ok', { operation: 'getProfileByUrn', selector: cacheKey });
+        (0, logger_1.log)("info", "api.ok", { operation: "getProfileByUrn", selector: cacheKey });
     }
     catch { }
     return prof;
 }
+/**
+ * Searches Sales Navigator for leads matching the given criteria.
+ * Supports pagination, advanced filters, and session-based account stickiness.
+ *
+ * @param keywords - Search keywords (max 2000 characters)
+ * @param options - Search configuration options
+ * @param options.start - Pagination offset (default: 0)
+ * @param options.count - Results per page (default: 25)
+ * @param options.decorationId - LinkedIn decoration ID for response format
+ * @param options.filters - Advanced search filters (title, company, geography, etc.)
+ * @param options.rawQuery - Raw query string (bypasses filter encoding)
+ * @param options.sessionId - Session ID for consistent pagination (same account across pages)
+ * @returns SearchSalesResult with items array, pagination info, and session metadata
+ * @throws LinkedInClientError with code INVALID_INPUT if keywords exceed max length
+ *
+ * @example
+ * ```typescript
+ * // Simple search
+ * const results = await searchSalesLeads('CEO');
+ *
+ * // Paginated search with session persistence
+ * const page1 = await searchSalesLeads('CEO', { start: 0, count: 25 });
+ * const sessionId = page1._meta?.sessionId;
+ * const page2 = await searchSalesLeads('CEO', { start: 25, count: 25, sessionId });
+ *
+ * // With filters
+ * const filtered = await searchSalesLeads('', {
+ *   filters: {
+ *     role: { seniority_ids: [8, 9, 10] }, // VP, CXO, Partner
+ *     company: { headcount: { include: ['501-1000', '1001-5000'] } }
+ *   }
+ * });
+ * ```
+ */
 async function searchSalesLeads(keywords, options) {
     const cfg = (0, config_1.getConfig)();
+    // Validate keyword length to prevent query injection and DoS
+    const MAX_KEYWORD_LENGTH = 2000;
+    const keywordsStr = String(keywords || "");
+    if (keywordsStr.length > MAX_KEYWORD_LENGTH) {
+        throw new errors_1.LinkedInClientError(`Search keywords too long (max ${MAX_KEYWORD_LENGTH} characters)`, errors_1.ERROR_CODES.INVALID_INPUT, 400);
+    }
     const start = Number.isFinite(options?.start) ? Number(options.start) : 0;
     const count = Number.isFinite(options?.count) ? Number(options.count) : 25;
-    const deco = options?.decorationId || 'com.linkedin.sales.deco.desktop.searchv2.LeadSearchResult-14';
-    // Generate or use provided sessionId
-    const sessionId = options?.sessionId || (await Promise.resolve().then(() => __importStar(require('crypto')))).randomUUID();
+    const deco = options?.decorationId ||
+        "com.linkedin.sales.deco.desktop.searchv2.LeadSearchResult-14";
     const sig = (0, search_encoder_1.buildFilterSignature)(options?.filters, options?.rawQuery);
-    // Phase 2.1: Include sessionId in cache key for session-specific caching
-    const cacheKey = JSON.stringify({ k: String(keywords || '').toLowerCase(), start, count, deco, sig, sessionId });
+    // Build cache key WITHOUT sessionId to enable cache hits across sessions with same query
+    // Only include sessionId in cache key if explicitly provided (for session-specific caching)
+    const cacheKeyObj = {
+        k: String(keywords || "").toLowerCase(),
+        start,
+        count,
+        deco,
+        sig,
+    };
+    if (options?.sessionId) {
+        cacheKeyObj.sessionId = options.sessionId;
+    }
+    const cacheKey = JSON.stringify(cacheKeyObj);
     const cached = getCached(searchCache, cacheKey, cfg.searchCacheTtl);
     if (cached) {
-        (0, metrics_1.incrementMetric)('searchCacheHits');
+        (0, metrics_1.incrementMetric)("searchCacheHits");
         return cached;
     }
+    // Generate sessionId AFTER cache lookup to avoid breaking cache keys
+    const sessionId = options?.sessionId || (await Promise.resolve().then(() => __importStar(require("crypto")))).randomUUID();
     let queryStruct;
     if (options?.rawQuery) {
         queryStruct = String(options.rawQuery);
@@ -265,16 +407,22 @@ async function searchSalesLeads(keywords, options) {
     async function doRequest(decorationId) {
         const url = `${SALES_NAV_BASE}/salesApiLeadSearch?q=searchQuery&start=${start}&count=${count}&decorationId=${encodeURIComponent(decorationId)}&query=${queryStruct}`;
         try {
-            (0, logger_1.log)('info', 'api.start', { operation: 'searchSalesLeads', selector: { keywords, start, count, deco: decorationId, sessionId } });
+            (0, logger_1.log)("info", "api.start", {
+                operation: "searchSalesLeads",
+                selector: { keywords, start, count, deco: decorationId, sessionId },
+            });
         }
         catch { }
         const out = await (0, http_client_1.executeLinkedInRequest)({
             url,
-            headers: { Referer: 'https://www.linkedin.com/sales/search/people' },
+            headers: { Referer: "https://www.linkedin.com/sales/search/people" },
             sessionId, // Phase 2.1: Pass sessionId for account stickiness
-        }, 'searchSalesLeads');
+        }, "searchSalesLeads");
         try {
-            (0, logger_1.log)('info', 'api.ok', { operation: 'searchSalesLeads', selector: { keywords, start, count, deco: decorationId, sessionId } });
+            (0, logger_1.log)("info", "api.ok", {
+                operation: "searchSalesLeads",
+                selector: { keywords, start, count, deco: decorationId, sessionId },
+            });
         }
         catch { }
         return out;
@@ -282,31 +430,44 @@ async function searchSalesLeads(keywords, options) {
     // Use only the specified decoration ID - no fallbacks to ensure consistent data structure
     const raw = await doRequest(deco);
     const items = (0, search_parser_1.parseSalesSearchResults)(raw);
-    const rrec = (raw && typeof raw === 'object') ? raw : undefined;
-    const pagingVal = rrec && 'paging' in rrec ? rrec.paging : undefined;
-    const p = (pagingVal && typeof pagingVal === 'object') ? pagingVal : undefined;
+    const rrec = raw && typeof raw === "object"
+        ? raw
+        : undefined;
+    const pagingVal = rrec && "paging" in rrec
+        ? rrec.paging
+        : undefined;
+    const p = pagingVal && typeof pagingVal === "object"
+        ? pagingVal
+        : undefined;
     const paging = p ?? { start, count };
     // Extract metadata.totalDisplayCount (LinkedIn's display string like "500K+")
-    const metadataVal = rrec && 'metadata' in rrec ? rrec.metadata : undefined;
-    const metadata = (metadataVal && typeof metadataVal === 'object') ? metadataVal : undefined;
+    const metadataVal = rrec && "metadata" in rrec
+        ? rrec.metadata
+        : undefined;
+    const metadata = metadataVal && typeof metadataVal === "object"
+        ? metadataVal
+        : undefined;
     // Calculate hasMore using LinkedIn's total count (primary) or result length (fallback)
     // LinkedIn API always returns paging.total, so we use it for accurate pagination
-    const hasMore = paging?.total ? (start + count) < paging.total : items.length === count;
-    const result = options
-        ? {
-            items,
-            page: {
-                start: Number(paging.start ?? start),
-                count: Number(paging.count ?? count),
-                total: paging?.total,
-                hasMore
-            },
-            metadata: metadata?.totalDisplayCount ? { totalDisplayCount: metadata.totalDisplayCount } : undefined,
-            _meta: { sessionId } // Return sessionId to consumer
-        }
-        : items; // backward-compat: old tests expect an array when no options passed
+    const hasMore = paging?.total
+        ? start + count < paging.total
+        : items.length === count;
+    // Always return SearchSalesResult for consistent API (breaking change from v0.3.x)
+    const result = {
+        items,
+        page: {
+            start: Number(paging.start ?? start),
+            count: Number(paging.count ?? count),
+            total: paging?.total,
+            hasMore,
+        },
+        metadata: metadata?.totalDisplayCount
+            ? { totalDisplayCount: metadata.totalDisplayCount }
+            : undefined,
+        _meta: { sessionId }, // Return sessionId to consumer
+    };
     searchCache.set(cacheKey, { data: result, ts: Date.now() });
-    (0, metrics_1.incrementMetric)('searchCacheMisses');
+    (0, metrics_1.incrementMetric)("searchCacheMisses");
     return result;
 }
 async function getProfilesBatch(vanities, concurrency = 4) {
@@ -334,55 +495,92 @@ async function getProfilesBatch(vanities, concurrency = 4) {
 // Companies (Voyager organizations)
 // ---------------------------------------------------------------------------
 async function resolveCompanyUniversalName(universalName) {
-    const url = `${LINKEDIN_API_BASE}/organization/companies?q=universalName&universalName=${encodeURIComponent(String(universalName || '').trim())}`;
+    const url = `${LINKEDIN_API_BASE}/organization/companies?q=universalName&universalName=${encodeURIComponent(String(universalName || "").trim())}`;
     try {
         try {
-            (0, logger_1.log)('info', 'api.start', { operation: 'resolveCompanyUniversalName', selector: universalName });
+            (0, logger_1.log)("info", "api.start", {
+                operation: "resolveCompanyUniversalName",
+                selector: universalName,
+            });
         }
         catch { }
-        const raw = await (0, http_client_1.executeLinkedInRequest)({ url }, 'resolveCompanyUniversalName');
-        const rec = (raw && typeof raw === 'object') ? raw : undefined;
-        const elementsVal = rec && 'elements' in rec ? rec.elements : undefined;
-        const first = Array.isArray(elementsVal) ? elementsVal[0] : undefined;
-        const id = first?.id ?? first?.entityUrn ?? undefined;
+        const raw = await (0, http_client_1.executeLinkedInRequest)({ url }, "resolveCompanyUniversalName");
+        const rec = raw && typeof raw === "object"
+            ? raw
+            : undefined;
+        const elementsVal = rec && "elements" in rec
+            ? rec.elements
+            : undefined;
+        const first = Array.isArray(elementsVal)
+            ? elementsVal[0]
+            : undefined;
+        const id = first?.id ??
+            first?.entityUrn ??
+            undefined;
         try {
-            (0, logger_1.log)('info', 'api.ok', { operation: 'resolveCompanyUniversalName', selector: universalName, id });
+            (0, logger_1.log)("info", "api.ok", {
+                operation: "resolveCompanyUniversalName",
+                selector: universalName,
+                id,
+            });
         }
         catch { }
-        return { companyId: id ? String(id).replace(/^urn:li:fsd_company:/, '') : undefined };
+        return {
+            companyId: id
+                ? String(id).replace(/^urn:li:fsd_company:/, "")
+                : undefined,
+        };
     }
     catch (e) {
         const status = e?.status ?? 0;
         if (status === 404) {
             try {
-                (0, logger_1.log)('warn', 'api.notFound', { operation: 'resolveCompanyUniversalName', selector: universalName, status });
+                (0, logger_1.log)("warn", "api.notFound", {
+                    operation: "resolveCompanyUniversalName",
+                    selector: universalName,
+                    status,
+                });
             }
             catch { }
-            throw new errors_1.LinkedInClientError('Company not found', errors_1.ERROR_CODES.NOT_FOUND, 404);
+            throw new errors_1.LinkedInClientError("Company not found", errors_1.ERROR_CODES.NOT_FOUND, 404);
         }
         throw e;
     }
 }
+/**
+ * Fetches a company by its numeric LinkedIn ID.
+ * Results are cached for the configured TTL (default: 10 minutes).
+ *
+ * @param companyId - Numeric company ID (e.g., "1234567")
+ * @returns Company object with name, description, size, headquarters, etc.
+ * @throws LinkedInClientError with code NOT_FOUND if company doesn't exist
+ *
+ * @example
+ * ```typescript
+ * const company = await getCompanyById('1234567');
+ * console.log(company.name, company.sizeLabel);
+ * ```
+ */
 async function getCompanyById(companyId) {
     const cfg = (0, config_1.getConfig)();
-    const key = String(companyId || '').trim();
+    const key = String(companyId || "").trim();
     const cached = getCached(companyCache, key, cfg.companyCacheTtl);
     if (cached) {
-        (0, metrics_1.incrementMetric)('companyCacheHits');
+        (0, metrics_1.incrementMetric)("companyCacheHits");
         return cached;
     }
     const url = `${LINKEDIN_API_BASE}/entities/companies/${encodeURIComponent(key)}`;
     try {
         try {
-            (0, logger_1.log)('info', 'api.start', { operation: 'getCompanyById', selector: key });
+            (0, logger_1.log)("info", "api.start", { operation: "getCompanyById", selector: key });
         }
         catch { }
-        const raw = await (0, http_client_1.executeLinkedInRequest)({ url }, 'getCompanyById');
+        const raw = await (0, http_client_1.executeLinkedInRequest)({ url }, "getCompanyById");
         const parsed = (0, company_parser_1.parseCompany)(raw);
-        (0, metrics_1.incrementMetric)('companyFetches');
+        (0, metrics_1.incrementMetric)("companyFetches");
         companyCache.set(key, { data: parsed, ts: Date.now() });
         try {
-            (0, logger_1.log)('info', 'api.ok', { operation: 'getCompanyById', selector: key });
+            (0, logger_1.log)("info", "api.ok", { operation: "getCompanyById", selector: key });
         }
         catch { }
         return parsed;
@@ -391,35 +589,41 @@ async function getCompanyById(companyId) {
         const status = e?.status ?? 0;
         if (status === 404) {
             try {
-                (0, logger_1.log)('warn', 'api.notFound', { operation: 'getCompanyById', selector: key, status });
+                (0, logger_1.log)("warn", "api.notFound", {
+                    operation: "getCompanyById",
+                    selector: key,
+                    status,
+                });
             }
             catch { }
-            throw new errors_1.LinkedInClientError('Company not found', errors_1.ERROR_CODES.NOT_FOUND, 404);
+            throw new errors_1.LinkedInClientError("Company not found", errors_1.ERROR_CODES.NOT_FOUND, 404);
         }
         throw e;
     }
 }
 async function getCompanyByUrl(companyUrl) {
-    const input = String(companyUrl || '').trim();
+    const input = String(companyUrl || "").trim();
     let url;
     try {
         // Require explicit http/https scheme; do not auto-prepend
         if (!/^https?:\/\//i.test(input)) {
-            throw new errors_1.LinkedInClientError('Invalid company URL scheme', errors_1.ERROR_CODES.INVALID_INPUT, 400);
+            throw new errors_1.LinkedInClientError("Invalid company URL scheme", errors_1.ERROR_CODES.INVALID_INPUT, 400);
         }
         url = new URL(input);
     }
     catch {
-        throw new errors_1.LinkedInClientError('Invalid company URL', errors_1.ERROR_CODES.INVALID_INPUT, 400);
+        throw new errors_1.LinkedInClientError("Invalid company URL", errors_1.ERROR_CODES.INVALID_INPUT, 400);
     }
     const m = url.pathname.match(/\/company\/([^\/]+)/i);
     if (!m) {
         try {
-            (0, logger_1.log)('error', 'api.invalidInput', { operation: 'getCompanyByUrl', selector: companyUrl });
+            (0, logger_1.log)("error", "api.invalidInput", {
+                operation: "getCompanyByUrl",
+                selector: companyUrl,
+            });
         }
         catch { }
-        ;
-        throw new errors_1.LinkedInClientError('Invalid company URL path', errors_1.ERROR_CODES.INVALID_INPUT, 400);
+        throw new errors_1.LinkedInClientError("Invalid company URL path", errors_1.ERROR_CODES.INVALID_INPUT, 400);
     }
     const ident = decodeURIComponent(m[1]);
     if (/^\d+$/.test(ident)) {
@@ -428,50 +632,86 @@ async function getCompanyByUrl(companyUrl) {
     const resolved = await resolveCompanyUniversalName(ident);
     if (!resolved.companyId) {
         try {
-            (0, logger_1.log)('warn', 'api.notFound', { operation: 'getCompanyByUrl', selector: companyUrl });
+            (0, logger_1.log)("warn", "api.notFound", {
+                operation: "getCompanyByUrl",
+                selector: companyUrl,
+            });
         }
         catch { }
-        ;
-        throw new errors_1.LinkedInClientError('Company not found', errors_1.ERROR_CODES.NOT_FOUND, 404);
+        throw new errors_1.LinkedInClientError("Company not found", errors_1.ERROR_CODES.NOT_FOUND, 404);
     }
     return getCompanyById(resolved.companyId);
 }
+/**
+ * Fetch multiple companies in parallel with controlled concurrency.
+ * @param companyIds - Array of company IDs (numeric strings)
+ * @param concurrency - Maximum parallel requests (default: 4, max: 16)
+ * @returns Array of Company objects (null for failed fetches, preserves order)
+ */
+async function getCompaniesBatch(companyIds, concurrency = 4) {
+    const limit = Math.max(1, Math.min(concurrency || 1, 16));
+    const results = Array.from({ length: companyIds.length }, () => null);
+    let idx = 0;
+    async function worker() {
+        while (idx < companyIds.length) {
+            const myIdx = idx++;
+            const companyId = companyIds[myIdx];
+            try {
+                const company = await getCompanyById(companyId);
+                results[myIdx] = company ?? null;
+            }
+            catch {
+                results[myIdx] = null;
+            }
+        }
+    }
+    const workers = Array.from({ length: Math.min(limit, companyIds.length) }, () => worker());
+    await Promise.all(workers);
+    return results;
+}
 // ---------------------------------------------------------------------------
 // Typeahead (Sales Navigator facets)
 // ---------------------------------------------------------------------------
 async function typeahead(options) {
     const cfg = (0, config_1.getConfig)();
-    const type = String(options?.type || '').trim();
+    const type = String(options?.type || "").trim();
     const start = Number.isFinite(options?.start) ? Number(options.start) : 0;
     const count = Number.isFinite(options?.count) ? Number(options.count) : 10;
-    const query = (options?.query ?? '').toString().trim();
+    const query = (options?.query ?? "").toString().trim();
     // Return static defaults when no query provided for supported types
     if (!query) {
         let staticOptions;
         switch (type) {
-            case 'FUNCTION':
+            case "FUNCTION":
                 staticOptions = constants_1.FUNCTION_OPTIONS;
                 break;
-            case 'BING_GEO':
+            case "BING_GEO":
                 staticOptions = constants_1.REGION_OPTIONS;
                 break;
-            case 'PROFILE_LANGUAGE':
+            case "PROFILE_LANGUAGE":
                 staticOptions = constants_1.LANGUAGE_OPTIONS;
                 break;
-            case 'INDUSTRY':
+            case "INDUSTRY":
                 staticOptions = constants_1.INDUSTRY_OPTIONS;
                 break;
-            case 'SENIORITY_LEVEL':
+            case "SENIORITY_LEVEL":
                 staticOptions = constants_1.SENIORITY_OPTIONS;
                 break;
-            case 'COMPANY_SIZE':
+            case "COMPANY_SIZE":
                 staticOptions = constants_1.COMPANY_SIZE_OPTIONS;
                 break;
         }
         if (staticOptions) {
             return {
-                items: staticOptions.map(opt => ({ id: String(opt.id), text: opt.text })),
-                page: { start: 0, count: staticOptions.length, total: staticOptions.length }
+                items: staticOptions.map((opt) => ({
+                    id: String(opt.id),
+                    text: opt.text,
+                })),
+                page: {
+                    start: 0,
+                    count: staticOptions.length,
+                    total: staticOptions.length,
+                },
             };
         }
     }
@@ -479,36 +719,58 @@ async function typeahead(options) {
     const cacheKey = JSON.stringify({ type, query, start, count });
     const cached = getCached(typeaheadCache, cacheKey, cfg.typeaheadCacheTtl);
     if (cached) {
-        (0, metrics_1.incrementMetric)('typeaheadCacheHits');
+        (0, metrics_1.incrementMetric)("typeaheadCacheHits");
         return cached;
     }
     let url = `${SALES_NAV_BASE}/salesApiFacetTypeahead?q=query&type=${encodeURIComponent(type)}&start=${start}&count=${count}`;
     if (query)
         url += `&query=${encodeURIComponent(query)}`;
-    (0, metrics_1.incrementMetric)('typeaheadRequests');
+    (0, metrics_1.incrementMetric)("typeaheadRequests");
     try {
-        (0, logger_1.log)('info', 'api.start', { operation: 'typeahead', selector: { type, query, start, count } });
+        (0, logger_1.log)("info", "api.start", {
+            operation: "typeahead",
+            selector: { type, query, start, count },
+        });
     }
     catch { }
-    const raw = await (0, http_client_1.executeLinkedInRequest)({ url }, 'typeahead');
+    const raw = await (0, http_client_1.executeLinkedInRequest)({ url }, "typeahead");
     const items = Array.isArray(raw?.elements)
         ? raw.elements.map((it) => ({
-            id: String(it?.id ?? it?.backendId ?? ''),
+            id: String(it?.id ??
+                it?.backendId ??
+                ""),
             text: it.displayValue ??
                 it.headline?.text ??
                 it.text ??
                 it.name ??
                 it.label ??
-                ''
+                "",
         }))
         : [];
-    const rtype = (raw && typeof raw === 'object') ? raw : undefined;
-    const pagingVal2 = rtype && 'paging' in rtype ? rtype.paging : undefined;
-    const paging2 = (pagingVal2 && typeof pagingVal2 === 'object') ? pagingVal2 : undefined;
-    const result = { items, page: { start: Number(paging2?.start ?? start), count: Number(paging2?.count ?? count), total: paging2?.total } };
+    const rtype = raw && typeof raw === "object"
+        ? raw
+        : undefined;
+    const pagingVal2 = rtype && "paging" in rtype
+        ? rtype.paging
+        : undefined;
+    const paging2 = pagingVal2 && typeof pagingVal2 === "object"
+        ? pagingVal2
+        : undefined;
+    const result = {
+        items,
+        page: {
+            start: Number(paging2?.start ?? start),
+            count: Number(paging2?.count ?? count),
+            total: paging2?.total,
+        },
+    };
     typeaheadCache.set(cacheKey, { data: result, ts: Date.now() });
     try {
-        (0, logger_1.log)('info', 'api.ok', { operation: 'typeahead', selector: { type, query }, count: items.length });
+        (0, logger_1.log)("info", "api.ok", {
+            operation: "typeahead",
+            selector: { type, query },
+            count: items.length,
+        });
     }
     catch { }
     return result;
@@ -532,12 +794,12 @@ Object.defineProperty(exports, "COMPANY_SIZE_OPTIONS", { enumerable: true, get:
  */
 async function getYearsAtCompanyOptions() {
     return {
-        items: constants_1.YEARS_OPTIONS.map(opt => ({ id: opt.id, text: opt.text })),
+        items: constants_1.YEARS_OPTIONS.map((opt) => ({ id: opt.id, text: opt.text })),
         page: {
             start: 0,
             count: constants_1.YEARS_OPTIONS.length,
-            total: constants_1.YEARS_OPTIONS.length
-        }
+            total: constants_1.YEARS_OPTIONS.length,
+        },
     };
 }
 /**
@@ -545,12 +807,12 @@ async function getYearsAtCompanyOptions() {
  */
 async function getYearsInPositionOptions() {
     return {
-        items: constants_1.YEARS_OPTIONS.map(opt => ({ id: opt.id, text: opt.text })),
+        items: constants_1.YEARS_OPTIONS.map((opt) => ({ id: opt.id, text: opt.text })),
         page: {
             start: 0,
             count: constants_1.YEARS_OPTIONS.length,
-            total: constants_1.YEARS_OPTIONS.length
-        }
+            total: constants_1.YEARS_OPTIONS.length,
+        },
     };
 }
 /**
@@ -558,21 +820,21 @@ async function getYearsInPositionOptions() {
  */
 async function getYearsOfExperienceOptions() {
     return {
-        items: constants_1.YEARS_OPTIONS.map(opt => ({ id: opt.id, text: opt.text })),
+        items: constants_1.YEARS_OPTIONS.map((opt) => ({ id: opt.id, text: opt.text })),
         page: {
             start: 0,
             count: constants_1.YEARS_OPTIONS.length,
-            total: constants_1.YEARS_OPTIONS.length
-        }
+            total: constants_1.YEARS_OPTIONS.length,
+        },
     };
 }
 // ---------------------------------------------------------------------------
 // Sales Navigator profile details
 // ---------------------------------------------------------------------------
 async function getSalesNavigatorProfileDetails(profileUrnOrId) {
-    const idOrUrn = String(profileUrnOrId || '').trim();
+    const idOrUrn = String(profileUrnOrId || "").trim();
     // Build Sales API path supporting URN triple or explicit profileId/authType/authToken
-    let pathSeg = '';
+    let pathSeg = "";
     let pidFromTriple = null;
     // URN with triple
     const mUrn = idOrUrn.match(/^urn:li:(?:fs_salesProfile|fsd_profile):\(([^,\s)]+),([^,\s)]+),([^,\s)]+)\)/i);
@@ -581,25 +843,35 @@ async function getSalesNavigatorProfileDetails(profileUrnOrId) {
         pathSeg = `(profileId:${pid},authType:${authType},authToken:${authToken})`;
         pidFromTriple = pid;
     }
-    else if (/profileId:/.test(idOrUrn) && /authType:/.test(idOrUrn) && /authToken:/.test(idOrUrn)) {
+    else if (/profileId:/.test(idOrUrn) &&
+        /authType:/.test(idOrUrn) &&
+        /authToken:/.test(idOrUrn)) {
         // Already the triple form without urn prefix
-        pathSeg = `(${idOrUrn.replace(/^\(|\)$/g, '')})`;
+        pathSeg = `(${idOrUrn.replace(/^\(|\)$/g, "")})`;
         const m = idOrUrn.match(/profileId:([^,\s)]+)/);
         pidFromTriple = m ? m[1] : null;
     }
     else {
         // Fallback to simple id/urn
-        pathSeg = idOrUrn.startsWith('urn:') ? idOrUrn : encodeURIComponent(idOrUrn);
+        pathSeg = idOrUrn.startsWith("urn:")
+            ? idOrUrn
+            : encodeURIComponent(idOrUrn);
     }
-    const decoration = encodeURIComponent('(entityUrn,objectUrn,firstName,lastName,fullName,headline,pronoun,degree,profileUnlockInfo,location,listCount,summary,savedLead,defaultPosition,contactInfo,crmStatus,pendingInvitation,unlocked,flagshipProfileUrl,positions*(companyName,current,new,description,endedOn,posId,startedOn,title,location,companyUrn~fs_salesCompany(entityUrn,name,companyPictureDisplayImage)))');
+    const decoration = encodeURIComponent("(entityUrn,objectUrn,firstName,lastName,fullName,headline,pronoun,degree,profileUnlockInfo,location,listCount,summary,savedLead,defaultPosition,contactInfo,crmStatus,pendingInvitation,unlocked,flagshipProfileUrl,positions*(companyName,current,new,description,endedOn,posId,startedOn,title,location,companyUrn~fs_salesCompany(entityUrn,name,companyPictureDisplayImage)))");
     const base = `${SALES_NAV_BASE}/salesApiProfiles/`;
     async function requestWith(seg) {
         const url = `${base}${seg}?decoration=${decoration}`;
-        return (0, http_client_1.executeLinkedInRequest)({ url, headers: { Referer: 'https://www.linkedin.com/sales/search/people' } }, 'getSalesNavigatorProfileDetails');
+        return (0, http_client_1.executeLinkedInRequest)({
+            url,
+            headers: { Referer: "https://www.linkedin.com/sales/search/people" },
+        }, "getSalesNavigatorProfileDetails");
     }
     try {
         try {
-            (0, logger_1.log)('info', 'api.start', { operation: 'getSalesNavigatorProfileDetails', selector: idOrUrn });
+            (0, logger_1.log)("info", "api.start", {
+                operation: "getSalesNavigatorProfileDetails",
+                selector: idOrUrn,
+            });
         }
         catch { }
         let raw;
@@ -612,24 +884,34 @@ async function getSalesNavigatorProfileDetails(profileUrnOrId) {
                 // Fallback: some environments reject the triple form; retry with bare id
                 const fallbackSeg = encodeURIComponent(pidFromTriple);
                 try {
-                    (0, logger_1.log)('warn', 'api.salesProfileFallback', { from: pathSeg, to: fallbackSeg });
+                    (0, logger_1.log)("warn", "api.salesProfileFallback", {
+                        from: pathSeg,
+                        to: fallbackSeg,
+                    });
                 }
                 catch { }
                 raw = await requestWith(fallbackSeg);
             }
             else if (status === 404) {
                 try {
-                    (0, logger_1.log)('warn', 'api.notFound', { operation: 'getSalesNavigatorProfileDetails', selector: idOrUrn, status });
+                    (0, logger_1.log)("warn", "api.notFound", {
+                        operation: "getSalesNavigatorProfileDetails",
+                        selector: idOrUrn,
+                        status,
+                    });
                 }
                 catch { }
-                throw new errors_1.LinkedInClientError('Sales profile not found', errors_1.ERROR_CODES.NOT_FOUND, 404);
+                throw new errors_1.LinkedInClientError("Sales profile not found", errors_1.ERROR_CODES.NOT_FOUND, 404);
             }
             else {
                 throw e;
             }
         }
         try {
-            (0, logger_1.log)('info', 'api.ok', { operation: 'getSalesNavigatorProfileDetails', selector: idOrUrn });
+            (0, logger_1.log)("info", "api.ok", {
+                operation: "getSalesNavigatorProfileDetails",
+                selector: idOrUrn,
+            });
         }
         catch { }
         return raw;