linkedin-secret-sauce 0.3.29 → 0.4.0

package/dist/parsers/company-parser.d.ts

@@ -1,2 +1,16 @@
-import type { Company } from '../types';
+import type { Company } from "../types";
+/**
+ * Parses a LinkedIn company API response into a structured Company object.
+ * Handles multiple response formats (nested data + included array, or flat structure).
+ *
+ * @param raw - Raw API response from LinkedIn companies endpoint
+ * @returns Parsed Company object with name, description, size, logo, etc.
+ *
+ * @example
+ * ```typescript
+ * const raw = await executeLinkedInRequest({ url: companyUrl });
+ * const company = parseCompany(raw);
+ * console.log(company.name, company.sizeLabel);
+ * ```
+ */
 export declare function parseCompany(raw: unknown): Company;

package/dist/parsers/company-parser.js

@@ -2,37 +2,62 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.parseCompany = parseCompany;
 const image_parser_1 = require("./image-parser");
+/**
+ * Parses a LinkedIn company API response into a structured Company object.
+ * Handles multiple response formats (nested data + included array, or flat structure).
+ *
+ * @param raw - Raw API response from LinkedIn companies endpoint
+ * @returns Parsed Company object with name, description, size, logo, etc.
+ *
+ * @example
+ * ```typescript
+ * const raw = await executeLinkedInRequest({ url: companyUrl });
+ * const company = parseCompany(raw);
+ * console.log(company.name, company.sizeLabel);
+ * ```
+ */
 function parseCompany(raw) {
     const r = raw;
     // LinkedIn API returns nested structure with data + included array
     const data = r?.data || r;
-    const included = Array.isArray(r?.included) ? r.included : [];
+    const included = Array.isArray(r?.included)
+        ? r.included
+        : [];
     // Find MiniCompany in included array (contains name, logo, universalName)
-    const miniCompany = included.find(it => String(it?.entityUrn || '').includes('fs_miniCompany') ||
-        String(it?.$type || '').includes('MiniCompany'));
+    const miniCompany = included.find((it) => String(it?.entityUrn || "").includes("fs_miniCompany") ||
+        String(it?.$type || "").includes("MiniCompany"));
     // Extract company ID from multiple possible locations
     const extractId = (obj) => {
         if (!obj)
-            return '';
-        const id = String(obj.id ?? obj.entityUrn ?? obj.objectUrn ?? '');
+            return "";
+        const id = String(obj.id ?? obj.entityUrn ?? obj.objectUrn ?? "");
         // Handle all URN formats: fs_miniCompany, fs_company, fsd_company
-        return id.replace(/^urn:li:(?:fsd_|fs_)?(?:miniCompany|company):/i, '');
+        return id.replace(/^urn:li:(?:fsd_|fs_)?(?:miniCompany|company):/i, "");
     };
     // Priority: data.entityUrn > miniCompany.objectUrn > miniCompany.entityUrn > data.id
     const companyId = extractId(data) || extractId(miniCompany) || extractId(r);
     const company = {
         companyId,
-        universalName: (miniCompany?.universalName || data?.universalName || r?.universalName),
+        universalName: (miniCompany?.universalName ||
+            data?.universalName ||
+            r?.universalName),
         name: (miniCompany?.name || data?.name || r?.name),
         websiteUrl: (data?.websiteUrl || r?.websiteUrl),
         description: (data?.description || r?.description),
-        sizeLabel: (typeof data?.employeeCountRange === 'string' ? data.employeeCountRange :
-            data?.employeeCountRange?.localizedName) ||
-            (typeof r?.employeeCountRange === 'string' ? r.employeeCountRange :
-                r?.employeeCountRange?.localizedName),
-        headquarters: data?.basicCompanyInfo?.headquarters ||
-            r?.headquarterLocation?.defaultLocalizedName ||
-            r?.headquarter?.defaultLocalizedName,
+        sizeLabel: (typeof data?.employeeCountRange === "string"
+            ? data.employeeCountRange
+            : data?.employeeCountRange
+                ?.localizedName) ||
+            (typeof r?.employeeCountRange === "string"
+                ? r.employeeCountRange
+                : r?.employeeCountRange
+                    ?.localizedName),
+        headquarters: data?.basicCompanyInfo
+            ?.headquarters ||
+            r?.headquarterLocation
+                ?.defaultLocalizedName ||
+            r?.headquarter
+                ?.defaultLocalizedName,
         companyType: (data?.companyType || r?.companyType),
         industries: (data?.industries || r?.industries),
         specialties: (data?.specialties || r?.specialties),
@@ -42,14 +67,17 @@ function parseCompany(raw) {
         coverUrl: undefined,
     };
     // Extract logo - check miniCompany first, then data, then root
-    const logoVector = miniCompany?.logo?.vectorImage ||
+    const logoVector = miniCompany?.logo
+        ?.vectorImage ||
         miniCompany?.logo ||
         data?.logo?.vectorImage ||
         r?.logo?.vectorImage ||
         r?.logoV2?.vectorImage;
-    const coverVector = data?.coverPhoto?.vectorImage ||
+    const coverVector = data?.coverPhoto
+        ?.vectorImage ||
         r?.coverPhoto?.vectorImage ||
-        r?.backgroundImage?.vectorImage;
+        r?.backgroundImage
+            ?.vectorImage;
     const logoUrl = (0, image_parser_1.selectBestImageUrl)(logoVector);
     const coverUrl = (0, image_parser_1.selectBestImageUrl)(coverVector);
     if (logoUrl)

package/dist/parsers/profile-parser.d.ts

@@ -1,2 +1,20 @@
-import type { LinkedInProfile } from '../types';
+import type { LinkedInProfile } from "../types";
+/**
+ * Parses a LinkedIn profile response from the Voyager API.
+ *
+ * @param rawResponse - Raw API response containing `included` array with profile entities
+ * @param vanity - The public identifier to match against; used to handle API returning multiple profiles
+ * @returns Structured LinkedInProfile with positions, education, skills, and metadata
+ *
+ * @remarks
+ * LinkedIn API responses contain an `included` array with various entity types.
+ * This parser extracts and correlates:
+ * - Profile identity (name, headline, summary, etc.)
+ * - Positions with company information
+ * - Education history
+ * - Skills
+ * - Avatar and cover images
+ *
+ * The parser uses O(n) complexity by building a URN lookup map upfront.
+ */
 export declare function parseFullProfile(rawResponse: unknown, vanity: string): LinkedInProfile;

package/dist/parsers/profile-parser.js

@@ -2,14 +2,43 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.parseFullProfile = parseFullProfile;
 const image_parser_1 = require("./image-parser");
+/**
+ * Parses a LinkedIn profile response from the Voyager API.
+ *
+ * @param rawResponse - Raw API response containing `included` array with profile entities
+ * @param vanity - The public identifier to match against; used to handle API returning multiple profiles
+ * @returns Structured LinkedInProfile with positions, education, skills, and metadata
+ *
+ * @remarks
+ * LinkedIn API responses contain an `included` array with various entity types.
+ * This parser extracts and correlates:
+ * - Profile identity (name, headline, summary, etc.)
+ * - Positions with company information
+ * - Education history
+ * - Skills
+ * - Avatar and cover images
+ *
+ * The parser uses O(n) complexity by building a URN lookup map upfront.
+ */
 function parseFullProfile(rawResponse, vanity) {
     const rr = rawResponse;
-    const included = Array.isArray(rr?.included) ? rr.included : [];
+    const included = Array.isArray(rr?.included)
+        ? rr.included
+        : [];
+    // Build URN lookup map for O(1) entity lookups (optimization from O(n²) to O(n))
+    const urnMap = new Map();
+    for (const item of included) {
+        const rec = item;
+        const entityUrn = rec?.entityUrn;
+        if (entityUrn) {
+            urnMap.set(entityUrn, rec);
+        }
+    }
     // FIX: Match profile by publicIdentifier to handle edge case where LinkedIn API
     // returns multiple profiles (e.g., authenticated user + requested profile)
     const identity = 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 by publicIdentifier if vanity was provided
@@ -20,7 +49,8 @@ function parseFullProfile(rawResponse, vanity) {
         }
         // Fallback: if no vanity to match, return first profile (legacy behavior for getProfileByUrn)
         return true;
-    }) || {};
+    }) ||
+        {};
     const profile = {
         vanity,
         publicIdentifier: identity.publicIdentifier,
@@ -37,26 +67,27 @@ function parseFullProfile(rawResponse, vanity) {
         positions: [],
         educations: [],
     };
-    // Extract geoLocation and countryCode
+    // Extract geoLocation and countryCode using O(1) lookup
     const geoLocation = identity.geoLocation;
     if (geoLocation?.geoUrn) {
         profile.geoLocationUrn = geoLocation.geoUrn;
-        // Lookup the geo object in included array to get the actual location name
-        const geoUrn = geoLocation.geoUrn;
-        const geoObj = included.find((it) => it?.entityUrn === geoUrn);
+        // O(1) lookup for geo object
+        const geoObj = urnMap.get(geoLocation.geoUrn);
         if (geoObj?.defaultLocalizedName) {
             profile.locationText = geoObj.defaultLocalizedName;
         }
     }
     // Fallback to direct location fields if geo lookup didn't work
     if (!profile.locationText) {
-        profile.locationText = identity.locationName || identity.geoLocationName;
+        profile.locationText =
+            identity.locationName ||
+                identity.geoLocationName;
     }
     const location = identity.location;
     if (location?.countryCode) {
         profile.countryCode = location.countryCode;
     }
-    // Positions
+    // Helper: Extract company ID from URN
     function extractCompanyIdFromUrn(urn) {
         if (!urn)
             return undefined;
@@ -67,19 +98,20 @@ function parseFullProfile(rawResponse, vanity) {
         const mSimple = s.match(/company:([^,\s)]+)/i);
         return mSimple ? mSimple[1] : undefined;
     }
+    // Helper: Deep find company URN in nested object (limited depth)
     function deepFindCompanyUrn(obj, depth = 0) {
         if (!obj || depth > 3)
             return undefined;
-        if (typeof obj === 'string' && /urn:li:(?:fsd_)?company:/i.test(obj))
+        if (typeof obj === "string" && /urn:li:(?:fsd_)?company:/i.test(obj))
             return obj;
-        if (typeof obj !== 'object')
+        if (typeof obj !== "object")
             return undefined;
         const rec = obj;
         for (const k of Object.keys(rec)) {
             const v = rec[k];
-            if (typeof v === 'string' && /urn:li:(?:fsd_)?company:/i.test(v))
+            if (typeof v === "string" && /urn:li:(?:fsd_)?company:/i.test(v))
                 return v;
-            if (v && typeof v === 'object') {
+            if (v && typeof v === "object") {
                 const hit = deepFindCompanyUrn(v, depth + 1);
                 if (hit)
                     return hit;
@@ -87,78 +119,95 @@ function parseFullProfile(rawResponse, vanity) {
         }
         return undefined;
     }
+    // Single pass through included array for positions, educations, and skills
     for (const item of included) {
         const rec = item;
-        const urn = rec?.entityUrn || '';
-        // Only match individual positions, exclude position groups
-        if (!urn.includes('urn:li:fsd_profilePosition:'))
-            continue;
-        const pos = {
-            title: rec?.title,
-            companyName: rec?.companyName,
-            description: rec?.description,
-            isCurrent: !rec?.timePeriod?.endDate && !rec?.dateRange?.end,
-            startYear: rec?.timePeriod?.startDate?.year || rec?.dateRange?.start?.year,
-            startMonth: rec?.timePeriod?.startDate?.month || rec?.dateRange?.start?.month,
-            endYear: rec?.timePeriod?.endDate?.year || rec?.dateRange?.end?.year,
-            endMonth: rec?.timePeriod?.endDate?.month || rec?.dateRange?.end?.month,
-        };
-        // Try to extract company URN and numeric id robustly
-        const candUrns = [
-            rec?.companyUrn,
-            rec?.company?.entityUrn,
-            rec?.company?.companyUrn,
-            rec?.companyUrnV2,
-        ].filter(Boolean);
-        const foundUrn = candUrns.find(u => /urn:li:(?:fsd_)?company:/i.test(u)) || deepFindCompanyUrn(item);
-        if (foundUrn) {
-            pos.companyUrn = foundUrn;
-            const cid = extractCompanyIdFromUrn(foundUrn);
-            if (cid)
-                pos.companyId = cid;
-            // Extract company logo from included array by dereferencing the URN
-            const companyObj = included.find(it => it?.entityUrn === foundUrn);
-            if (companyObj) {
-                const logoVector = companyObj.logo?.vectorImage;
-                const logoUrl = (0, image_parser_1.selectBestImageUrl)(logoVector);
-                if (logoUrl)
-                    pos.companyLogoUrl = logoUrl;
+        const urn = rec?.entityUrn || "";
+        // Parse positions
+        if (urn.includes("urn:li:fsd_profilePosition:")) {
+            const pos = {
+                title: rec?.title,
+                companyName: rec?.companyName,
+                description: rec?.description,
+                isCurrent: !rec?.timePeriod?.endDate &&
+                    !rec?.dateRange?.end,
+                startYear: rec?.timePeriod
+                    ?.startDate?.year ||
+                    rec?.dateRange?.start
+                        ?.year,
+                startMonth: rec?.timePeriod
+                    ?.startDate?.month ||
+                    rec?.dateRange?.start
+                        ?.month,
+                endYear: rec?.timePeriod
+                    ?.endDate?.year ||
+                    rec?.dateRange?.end
+                        ?.year,
+                endMonth: rec?.timePeriod
+                    ?.endDate?.month ||
+                    rec?.dateRange?.end
+                        ?.month,
+            };
+            // Try to extract company URN and numeric id robustly
+            const candUrns = [
+                rec?.companyUrn,
+                rec?.company?.entityUrn,
+                rec?.company?.companyUrn,
+                rec?.companyUrnV2,
+            ].filter(Boolean);
+            const foundUrn = candUrns.find((u) => /urn:li:(?:fsd_)?company:/i.test(u)) ||
+                deepFindCompanyUrn(item);
+            if (foundUrn) {
+                pos.companyUrn = foundUrn;
+                const cid = extractCompanyIdFromUrn(foundUrn);
+                if (cid)
+                    pos.companyId = cid;
+                // O(1) lookup for company logo
+                const companyObj = urnMap.get(foundUrn);
+                if (companyObj) {
+                    const logoVector = companyObj.logo?.vectorImage;
+                    const logoUrl = (0, image_parser_1.selectBestImageUrl)(logoVector);
+                    if (logoUrl)
+                        pos.companyLogoUrl = logoUrl;
+                }
             }
+            profile.positions.push(pos);
+        }
+        // Parse educations
+        else if (urn.includes("fsd_profileEducation")) {
+            const edu = {
+                schoolName: rec?.schoolName,
+                degree: rec?.degreeName,
+                fieldOfStudy: rec?.fieldOfStudy,
+                startYear: rec?.timePeriod
+                    ?.startDate?.year ||
+                    rec?.dateRange?.start
+                        ?.year,
+                startMonth: rec?.timePeriod
+                    ?.startDate?.month ||
+                    rec?.dateRange?.start
+                        ?.month,
+                endYear: rec?.timePeriod
+                    ?.endDate?.year ||
+                    rec?.dateRange?.end
+                        ?.year,
+                endMonth: rec?.timePeriod
+                    ?.endDate?.month ||
+                    rec?.dateRange?.end
+                        ?.month,
+            };
+            profile.educations.push(edu);
+        }
+        // Parse skills
+        else if (urn.includes("fsd_skill")) {
+            if (!profile.skills)
+                profile.skills = [];
+            profile.skills.push({
+                name: rec?.name,
+                entityUrn: urn,
+            });
         }
-        profile.positions.push(pos);
-    }
-    // Educations
-    for (const item of included) {
-        const rec = item;
-        const urn = rec?.entityUrn || '';
-        if (!urn.includes('fsd_profileEducation'))
-            continue;
-        const edu = {
-            schoolName: rec?.schoolName,
-            degree: rec?.degreeName,
-            fieldOfStudy: rec?.fieldOfStudy,
-            startYear: rec?.timePeriod?.startDate?.year || rec?.dateRange?.start?.year,
-            startMonth: rec?.timePeriod?.startDate?.month || rec?.dateRange?.start?.month,
-            endYear: rec?.timePeriod?.endDate?.year || rec?.dateRange?.end?.year,
-            endMonth: rec?.timePeriod?.endDate?.month || rec?.dateRange?.end?.month,
-        };
-        profile.educations.push(edu);
-    }
-    // Skills
-    const skills = [];
-    for (const item of included) {
-        const rec = item;
-        const urn = rec?.entityUrn || '';
-        if (!urn.includes('fsd_skill'))
-            continue;
-        const skill = {
-            name: rec?.name,
-            entityUrn: urn,
-        };
-        skills.push(skill);
     }
-    if (skills.length > 0)
-        profile.skills = skills;
     // Avatar - check identity.profilePicture first (primary source)
     const profilePicture = identity.profilePicture;
     const displayImageReference = profilePicture?.displayImageReference;
@@ -169,7 +218,8 @@ function parseFullProfile(rawResponse, vanity) {
     }
     else {
         // Fallback: search included array for backward compatibility
-        const avatarItem = included.find((it) => it?.vectorImage && JSON.stringify(it).includes('vectorImage'));
+        const avatarItem = included.find((it) => it?.vectorImage &&
+            JSON.stringify(it).includes("vectorImage"));
         const fallbackVector = avatarItem?.vectorImage;
         const fallbackUrl = (0, image_parser_1.selectBestImageUrl)(fallbackVector);
         if (fallbackUrl)

package/dist/parsers/search-parser.d.ts

@@ -1,2 +1,2 @@
-import type { SalesLeadSearchResult } from '../types';
+import type { SalesLeadSearchResult } from "../types";
 export declare function parseSalesSearchResults(rawResponse: unknown): SalesLeadSearchResult[];

package/dist/parsers/search-parser.js

@@ -4,13 +4,16 @@ exports.parseSalesSearchResults = parseSalesSearchResults;
 const json_sanitizer_1 = require("../utils/json-sanitizer");
 function parseSalesSearchResults(rawResponse) {
     const rr = rawResponse;
-    const elements = Array.isArray(rr?.elements) ? rr?.elements : [];
+    const elements = Array.isArray(rr?.elements)
+        ? rr?.elements
+        : [];
     const results = [];
     for (const el of elements) {
-        const name = [el?.firstName, el?.lastName].filter(Boolean).join(' ').trim() || undefined;
+        const name = [el?.firstName, el?.lastName].filter(Boolean).join(" ").trim() ||
+            undefined;
         const res = {
             name: (0, json_sanitizer_1.sanitizeForJson)(name),
-            headline: (0, json_sanitizer_1.sanitizeForJson)((el?.summary || '').split('\n')[0]?.slice(0, 180)),
+            headline: (0, json_sanitizer_1.sanitizeForJson)((el?.summary || "").split("\n")[0]?.slice(0, 180)),
             salesProfileUrn: el?.entityUrn,
             objectUrn: el?.objectUrn,
             geoRegion: (0, json_sanitizer_1.sanitizeForJson)(el?.geoRegion),
@@ -18,7 +21,7 @@ function parseSalesSearchResults(rawResponse) {
             summary: (0, json_sanitizer_1.sanitizeForJson)(el?.summary),
         };
         // fsdKey from URN patterns
-        const urn = String(el?.entityUrn || '');
+        const urn = String(el?.entityUrn || "");
         const m3 = urn.match(/^urn:li:(?:fs_salesProfile|fsd_profile):\(([^,)]+),([^,)]+),([^,)]+)\)/i);
         if (m3) {
             res.fsdKey = m3[1]?.trim();
@@ -34,11 +37,13 @@ function parseSalesSearchResults(rawResponse) {
         const img = el?.profilePictureDisplayImage;
         if (img?.rootUrl && Array.isArray(img?.artifacts) && img.artifacts.length) {
             const best = img.artifacts.reduce((p, c) => ((c?.width || 0) > (p?.width || 0) ? c : p), {});
-            const seg = best?.fileIdentifyingUrlPathSegment || '';
+            const seg = best?.fileIdentifyingUrlPathSegment || "";
             res.imageUrl = img.rootUrl + seg;
         }
         // Current position (backward compatible - extract from first position)
-        const pos = Array.isArray(el?.currentPositions) && el.currentPositions.length > 0 ? el.currentPositions[0] : undefined;
+        const pos = Array.isArray(el?.currentPositions) && el.currentPositions.length > 0
+            ? el.currentPositions[0]
+            : undefined;
         if (pos) {
             res.currentRole = (0, json_sanitizer_1.sanitizeForJson)(pos?.title);
             res.currentCompany = (0, json_sanitizer_1.sanitizeForJson)(pos?.companyName);
@@ -46,9 +51,11 @@ function parseSalesSearchResults(rawResponse) {
             const companyData = pos?.companyUrnResolutionResult;
             if (companyData?.companyPictureDisplayImage) {
                 const cImg = companyData.companyPictureDisplayImage;
-                if (cImg?.rootUrl && Array.isArray(cImg?.artifacts) && cImg.artifacts.length) {
+                if (cImg?.rootUrl &&
+                    Array.isArray(cImg?.artifacts) &&
+                    cImg.artifacts.length) {
                     const bestC = cImg.artifacts.reduce((p, c) => ((c?.width || 0) > (p?.width || 0) ? c : p), {});
-                    const segC = bestC?.fileIdentifyingUrlPathSegment || '';
+                    const segC = bestC?.fileIdentifyingUrlPathSegment || "";
                     res.companyLogoUrl = cImg.rootUrl + segC;
                 }
             }
@@ -65,10 +72,16 @@ function parseSalesSearchResults(rawResponse) {
         res.pendingInvitation = el?.pendingInvitation;
         res.blockThirdPartyDataSharing = el?.blockThirdPartyDataSharing;
         // Pass through full positions arrays
-        res.currentPositions = Array.isArray(el?.currentPositions) ? el.currentPositions : undefined;
-        res.pastPositions = Array.isArray(el?.pastPositions) ? el.pastPositions : undefined;
+        res.currentPositions = Array.isArray(el?.currentPositions)
+            ? el.currentPositions
+            : undefined;
+        res.pastPositions = Array.isArray(el?.pastPositions)
+            ? el.pastPositions
+            : undefined;
         // Pass through spotlight badges
-        res.spotlightBadges = Array.isArray(el?.spotlightBadges) ? el.spotlightBadges : undefined;
+        res.spotlightBadges = Array.isArray(el?.spotlightBadges)
+            ? el.spotlightBadges
+            : undefined;
         results.push(res);
     }
     return results;

package/dist/utils/logger.d.ts

@@ -1,2 +1,2 @@
-export type LogLevel = 'debug' | 'info' | 'warn' | 'error';
+export type LogLevel = "debug" | "info" | "warn" | "error";
 export declare function log(level: LogLevel, message: string, data?: unknown): void;

package/dist/utils/logger.js

@@ -9,14 +9,20 @@ const LEVELS = {
     error: 40,
 };
 const SECRET_KEYS = new Set([
-    'cosiallApiKey',
-    'apikey',
-    'apiKey',
-    'authorization',
-    'cookie',
-    'password',
-    'secret',
-    'set-cookie',
+    "cosiallApiKey",
+    "apikey",
+    "apiKey",
+    "authorization",
+    "cookie",
+    "password",
+    "secret",
+    "set-cookie",
+    "csrf",
+    "csrfToken",
+    "csrf-token",
+    "x-csrf-token",
+    "li_at",
+    "jsessionid",
 ]);
 function maskIfSecret(key, value) {
     if (!key)
@@ -24,27 +30,31 @@ function maskIfSecret(key, value) {
     const k = key.toLowerCase();
     for (const s of SECRET_KEYS) {
         if (k === s.toLowerCase()) {
-            if (typeof value === 'string') {
+            if (typeof value === "string") {
                 if (value.length <= 6)
-                    return '***';
+                    return "***";
                 return `${value.slice(0, 2)}***${value.slice(-2)}`;
             }
-            return '***';
+            return "***";
         }
     }
     return value;
 }
 function log(level, message, data) {
-    let configured = 'info';
+    let configured = "info";
     try {
-        configured = ((0, config_1.getConfig)().logLevel || 'info');
+        configured = ((0, config_1.getConfig)().logLevel || "info");
     }
     catch {
-        configured = 'info';
+        configured = "info";
     }
     if (LEVELS[level] < LEVELS[configured])
         return;
-    const payload = { timestamp: new Date().toISOString(), level, message };
+    const payload = {
+        timestamp: new Date().toISOString(),
+        level,
+        message,
+    };
     if (data !== undefined) {
         try {
             // Safe stringify with masking
@@ -53,15 +63,15 @@ function log(level, message, data) {
         }
         catch {
             // Fallback to shallow copy
-            payload.data = '[unserializable]';
+            payload.data = "[unserializable]";
         }
     }
     const line = JSON.stringify(payload);
     switch (level) {
-        case 'error':
+        case "error":
             console.error(line);
             break;
-        case 'warn':
+        case "warn":
             console.warn(line);
             break;
         default:

package/dist/utils/search-encoder.d.ts

@@ -1,4 +1,35 @@
-import type { SalesSearchFilters } from '../types';
+import type { SalesSearchFilters } from "../types";
+/**
+ * Creates a deterministic string representation of an object for use as cache keys.
+ * Sorts object keys recursively to ensure consistent output regardless of property order.
+ *
+ * @param obj - Any JSON-serializable value
+ * @returns Stable string representation suitable for cache key usage
+ */
 export declare function stableStringify(obj: unknown): string;
 export declare function buildFilterSignature(filters?: SalesSearchFilters, rawQuery?: string): string | undefined;
+/**
+ * Builds a Sales Navigator search query string from keywords and filters.
+ * Encodes the query in LinkedIn's proprietary format for the salesApiLeadSearch endpoint.
+ *
+ * @param keywords - Search keywords to include in the query
+ * @param filters - Optional SalesSearchFilters object with advanced criteria:
+ *   - role: seniority_ids, current_titles, past_titles, functions
+ *   - company: current, past, headcount, type
+ *   - personal: geography, industry_ids, profile_language, years_* ranges
+ * @returns Encoded query string ready for use in Sales Navigator API URL
+ *
+ * @example
+ * ```typescript
+ * // Simple keyword search
+ * const query = buildLeadSearchQuery('CEO');
+ * // Returns: "(keywords:CEO)"
+ *
+ * // With filters
+ * const query = buildLeadSearchQuery('', {
+ *   role: { seniority_ids: [9, 10] },
+ *   company: { headcount: { include: ['51-200', '201-500'] } }
+ * });
+ * ```
+ */
 export declare function buildLeadSearchQuery(keywords: string, filters?: SalesSearchFilters): string;