linkedin-secret-sauce 0.1.1 → 0.2.0

package/README.md

@@ -1,95 +1,228 @@
-LinkedIn Secret Sauce Client
+# LinkedIn Secret Sauce Client
 
-Private LinkedIn Sales Navigator client for server-side use. It handles cookie/account rotation, retries, caching, parsing, logging, and metrics so apps just call a simple API.
+Private, server-side LinkedIn Sales Navigator client. It manages cookies/accounts, retries, caching, and parsing so your app calls a small, typed API.
+
+For a step‑by‑step integration guide you can copy/paste into other apps, see `docs/INTEGRATION.md`.
+
+Advanced lead search
+- Strongly‑typed filters: see `docs/SALES_SEARCH.md` (seniority, titles with id or text, functions, industries, languages, regions, company headcount/type, years buckets, current company).
+- Relationship filters are intentionally not used (results are customer‑agnostic).
+- Past company is not emitted — only CURRENT_COMPANY is supported.
+- Power users: pass a full `rawQuery` string to `searchSalesLeads` if you already have the Sales Navigator `query=(...)` payload.
 
 - Node: >= 18 (uses global `fetch`)
-- Build: `pnpm build` (or `npm run build`)
-- Test: `pnpm test` (or `npm test`)
+- Build: `pnpm build`
+- Test: `pnpm test`
 
 ## Install
 
-From npm registry (recommended):
-
 ```bash
-# pnpm
+# pnpm (recommended)
 pnpm add linkedin-secret-sauce
 
-# or npm	npm install linkedin-secret-sauce
+# npm
+npm install linkedin-secret-sauce
 ```
 
-From Git (alternative):
+## Quick Start
 
-```bash
-pnpm add github:enerage/LinkedInSecretSouce#v0.1.0
-```
+```ts
+import {
+  initializeLinkedInClient,
+  getProfileByVanity,
+  getProfileByUrn,
+  searchSalesLeads,
+  resolveCompanyUniversalName,
+  getCompanyById,
+  getCompanyByUrl,
+  typeahead,
+  getSalesNavigatorProfileDetails,
+  type LinkedInProfile,
+  type SearchSalesResult,
+  type Company,
+  type TypeaheadResult,
+  type SalesNavigatorProfile,
+} from 'linkedin-secret-sauce';
 
-Note: Import path is the package name (`linkedin-secret-sauce`).
+initializeLinkedInClient({
+  cosiallApiUrl: process.env.COSIALL_API_URL!,
+  cosiallApiKey: process.env.COSIALL_API_KEY!,
+  proxyString: process.env.LINKEDIN_PROXY_STRING, // optional
+  logLevel: (process.env.LOG_LEVEL as any) || 'info',
+});
+
+const prof: LinkedInProfile = await getProfileByVanity('john-doe');
+const prof2 = await getProfileByUrn('urn:li:fsd_profile:ACwAAAbCdEf'); // URN or bare key
+
+// Search with paging; on HTTP 400, decoration -14 falls back to -17
+const leads: SearchSalesResult = await searchSalesLeads('cto fintech', { start: 50, count: 10 });
+
+// Companies
+const { companyId } = await resolveCompanyUniversalName('microsoft');
+const company: Company = await getCompanyById(companyId!);
+const sameCompany = await getCompanyByUrl('https://www.linkedin.com/company/microsoft/');
+
+// Typeahead (facet suggestions)
+const ta: TypeaheadResult = await typeahead({ type: 'BING_GEO', query: 'new', start: 0, count: 10 });
 
-## Configure (env or code)
+// Sales Navigator profile details
+const sales: SalesNavigatorProfile = await getSalesNavigatorProfileDetails('urn:li:fs_salesProfile:ACwAAA...');
+```
+
+## Environment & Config
 
 Required
-- `cosiallApiUrl`: Base URL of your Cosiall service (e.g., https://cosiall.example)
-- `cosiallApiKey`: API key for the Cosiall endpoint
+- `COSIALL_API_URL` – base URL of your Cosiall service (e.g., https://cosiall.example)
+- `COSIALL_API_KEY` – API key for the Cosiall endpoint
 
 Optional
-- `proxyString`: `host:port` or `host:port:user:pass` (applies to HTTP(S) requests)
-- `logLevel`: `debug` | `info` | `warn` | `error` (default `info`)
+- `LINKEDIN_PROXY_STRING` – `host:port` or `host:port:user:pass`
+- `LOG_LEVEL` – `debug` | `info` | `warn` | `error` (default `info`)
 
-Defaults (can be overridden in code)
-- `profileCacheTtl`: 900000 ms
-- `searchCacheTtl`: 180000 ms
-- `cookieRefreshInterval`: 900000 ms
-- `cookieFreshnessWindow`: 86400000 ms
-- `maxRetries`: 2, `retryDelayMs`: 700
-- `accountCooldownMs`: 5000, `maxFailuresBeforeCooldown`: 3
+Config defaults (override in code as needed)
+- `profileCacheTtl`: 900_000 ms (15m)
+- `searchCacheTtl`: 180_000 ms (3m)
+- `companyCacheTtl`: 600_000 ms (10m)
+- `typeaheadCacheTtl`: 3_600_000 ms (1h)
+- `cookieRefreshInterval`: 900_000 ms (15m)
+- `cookieFreshnessWindow`: 86_400_000 ms (24h)
+- `maxRetries`: 2 (5xx retry on same account)
+- `retryDelayMs`: 700 ms
+- `accountCooldownMs`: 5_000 ms
+- `maxFailuresBeforeCooldown`: 3
+- `maxRequestHistory`: 500
 
-## Initialize (run once on startup)
+## Public API (overview)
 
-```ts
-import { initializeLinkedInClient } from 'linkedin-secret-sauce';
+- Profiles
+  - `getProfileByVanity(vanity)` – cached 15m, in‑flight de‑dupe per key.
+  - `getProfileByUrn(keyOrUrn)` – accepts `ACwAA...` or URNs; normalizes to key.
+  - `getProfilesBatch(vanities, concurrency)` – returns array aligned to inputs; `null` for failures.
 
-initializeLinkedInClient({
-  cosiallApiUrl: process.env.COSIALL_API_URL!,
-  cosiallApiKey: process.env.COSIALL_API_KEY!,
-  proxyString: process.env.LINKEDIN_PROXY_STRING, // optional
-  logLevel: (process.env.LOG_LEVEL as any) || 'info',
-});
-```
+- Search
+  - `searchSalesLeads(keywords, { start, count, decorationId })` – when options are provided returns `{ items, page }`; on HTTP 400 with `-14` decoration automatically retries with `-17`.
 
-## Use the API
+- Companies
+  - `resolveCompanyUniversalName(universalName)` → `{ companyId? }` (404 → NOT_FOUND)
+  - `getCompanyById(companyId)` → `Company` (10m cache)
+  - `getCompanyByUrl(url)` – parses numeric id or slug, then fetches
 
-```ts
-import {
-  getProfileByVanity,
-  getProfileByUrn,
-  searchSalesLeads,
-  type LinkedInProfile,
-} from 'linkedin-secret-sauce';
+- Typeahead
+  - `typeahead({ type, query, start, count })` → `TypeaheadResult` (1h cache)
+
+- Sales Navigator profile
+  - `getSalesNavigatorProfileDetails(idOrUrn)` → `SalesNavigatorProfile` (404 → NOT_FOUND)
+
+## Errors
+
+All errors are `LinkedInClientError` with fields `{ code, status?, accountId? }`.
+
+Error codes (non‑exhaustive)
+- `NOT_INITIALIZED`, `NO_ACCOUNTS`, `NO_VALID_ACCOUNTS`
+- `MISSING_CSRF`, `REQUEST_FAILED`, `ALL_ACCOUNTS_FAILED`, `PARSE_ERROR`
+- `INVALID_INPUT`, `NOT_FOUND`, `AUTH_ERROR`, `RATE_LIMITED`
 
-// Fetch a profile by vanity handle (cached, resilient)
-const profile: LinkedInProfile = await getProfileByVanity('john-doe');
+## Caching, Metrics, Proxy
 
-// Fetch a profile by fsdKey/URN key
-const profileByUrn = await getProfileByUrn('fsdKey123');
+- Per‑process in‑memory caches with TTLs listed above. Expired entries are evicted on access.
+- In‑flight de‑dupe for `getProfileByVanity`.
+- HTTP client rotates accounts on 401/403/429 and retries 5xx on same account (`maxRetries`).
+- Metrics snapshot: `import { getSnapshot }` for counters (requests, retries, cache hits, etc.).
+- Request history: `import { getRequestHistory, clearRequestHistory }` for a bounded in‑memory log.
+- Proxy: set `proxyString` in config (formats `host:port` or `host:port:user:pass`).
 
-// Search Sales Navigator leads
-const results = await searchSalesLeads('cto fintech');
+### Request History and Metrics (example)
+
+```ts
+import { getRequestHistory, clearRequestHistory, getSnapshot } from 'linkedin-secret-sauce';
+
+clearRequestHistory();
+// ... make some API calls ...
+console.log(getRequestHistory()[0]);
+// {
+//   timestamp: 1730000000000,
+//   operation: 'getProfileByVanity',
+//   selector: 'https://www.linkedin.com/voyager/api/...profiles?q=memberIdentity&memberIdentity=john-doe',
+//   status: 200,
+//   durationMs: 123,
+//   accountId: 'acc1'
+// }
+
+console.log(getSnapshot());
+// {
+//   profileFetches: 12,
+//   profileCacheHits: 34,
+//   inflightDedupeHits: 2,
+//   searchCacheHits: 5,
+//   typeaheadCacheHits: 3,
+//   companyCacheHits: 4,
+//   httpRetries: 3,
+//   httpSuccess: 21,
+//   httpFailures: 2,
+//   companyFetches: 4,
+//   typeaheadRequests: 5,
+//   requestHistorySize: 42,
+//   authErrors: 1,
+//   ...
+// }
 ```
 
-Notes
-- The package manages cookies via your Cosiall endpoint; no DB needed.
-- In-memory caches reset on process restart (safe: cookies refresh automatically).
-- Logs are JSON and respect `logLevel`; sensitive fields (e.g., `cosiallApiKey`) are masked.
+### Accounts Summary
 
-## Common commands
+```ts
+import { getAccountsSummary } from 'linkedin-secret-sauce';
+
+const accounts = getAccountsSummary();
+// [
+//   {
+//     accountId: 'acc1',
+//     healthy: false,
+//     failures: 1,
+//     cooldownUntil: 1730005000000,
+//     cooldownRemainingMs: 4200,
+//     expiresAt: 1730010000, // epoch seconds (if provided by Cosiall)
+//     lastUsedAt: 1730004000123
+//   },
+//   {
+//     accountId: 'acc2',
+//     healthy: true,
+//     failures: 0,
+//     cooldownUntil: 0,
+//     cooldownRemainingMs: 0,
+//     expiresAt: 1730010000,
+//     lastUsedAt: 1730003999000
+//   }
+// ]
+```
 
-```bash
-# build JS + .d.ts to dist/
-pnpm build
+## Testing
 
-# run tests
+```bash
 pnpm test
-
-# typecheck only (no emit)
 pnpm exec tsc -p tsconfig.json --noEmit
 ```
+
+## Manual Publish (npm)
+
+- Pre-checks:
+  - Working tree is clean; tests pass; `pnpm build` produced `dist/`.
+  - `publishConfig.registry` points to `https://registry.npmjs.org/` (already set).
+  - No repo `.npmrc` that overrides registry to GitHub Packages.
+
+- Steps (local):
+  1) `npm login` (once per machine; ensure correct org/user)
+  2) `npm whoami` (sanity check)
+  3) Bump version: `npm version patch|minor|major`
+  4) Publish: `npm publish`
+  5) Push tags: `git push --follow-tags`
+
+Notes:
+- If your npm account enforces 2FA for publish, you’ll be prompted for an OTP.
+- For scoped packages that should be public, add `--access public` (not needed here because the package name is unscoped).
+- The “Publish your first package” button on GitHub targets GitHub Packages (`npm publish --registry=https://npm.pkg.github.com/`), not npmjs.com.
+
+
+## Playground (React + Vite)\n\nDev-only UI to exercise the library safely via a local server.\n\n- Start both server and client: \n  - pnpm dev:playground\n- Or separately: \n  - pnpm -C apps/playground run server (http://localhost:5175)\n  - pnpm -C apps/playground run client (http://localhost:5173)\n\nThe server initializes the library and exposes endpoints for profiles, companies, typeahead, sales search, and sales profile.\nMetrics and request history are exposed at /api/metrics and /api/history.\n\nBy default the server uses a dev stub for cookies at /api/flexiq/linkedin-cookies/all.\nTo use your Cosiall backend, set env vars: COSIALL_API_URL and COSIALL_API_KEY and remove the stub in pps/playground/server/index.ts.\n
+## Playground (local UI)
+
+See `docs/PLAYGROUND.md` for usage, ports, and tips.

package/dist/config.d.ts

@@ -5,12 +5,15 @@ export interface LinkedInClientConfig {
     logLevel?: 'debug' | 'info' | 'warn' | 'error';
     profileCacheTtl?: number;
     searchCacheTtl?: number;
+    companyCacheTtl?: number;
+    typeaheadCacheTtl?: number;
     cookieRefreshInterval?: number;
     cookieFreshnessWindow?: number;
     maxRetries?: number;
     retryDelayMs?: number;
     accountCooldownMs?: number;
     maxFailuresBeforeCooldown?: number;
+    maxRequestHistory?: number;
 }
 export declare function initializeLinkedInClient(config: LinkedInClientConfig): void;
 export declare function getConfig(): LinkedInClientConfig;

package/dist/config.js

@@ -11,7 +11,6 @@ function initializeLinkedInClient(config) {
     }
     // Validate URL format
     try {
-        // eslint-disable-next-line no-new
         new URL(config.cosiallApiUrl);
     }
     catch {
@@ -21,6 +20,8 @@ function initializeLinkedInClient(config) {
     const withDefaults = {
         profileCacheTtl: 15 * 60 * 1000,
         searchCacheTtl: 3 * 60 * 1000,
+        companyCacheTtl: 10 * 60 * 1000, // 600_000 ms
+        typeaheadCacheTtl: 60 * 60 * 1000, // 3_600_000 ms
         cookieRefreshInterval: 15 * 60 * 1000,
         cookieFreshnessWindow: 24 * 60 * 60 * 1000,
         maxRetries: 2,
@@ -28,6 +29,7 @@ function initializeLinkedInClient(config) {
         accountCooldownMs: 5000,
         maxFailuresBeforeCooldown: 3,
         logLevel: 'info',
+        maxRequestHistory: 500,
         ...config,
     };
     // Optionally mask API key from accidental JSON serialization
@@ -42,7 +44,10 @@ function initializeLinkedInClient(config) {
     catch {
         // ignore if defineProperty fails in exotic environments
     }
-    globalConfig = withDefaults;
+    // Idempotent: only set once; subsequent calls are no-ops
+    if (!globalConfig) {
+        globalConfig = withDefaults;
+    }
 }
 function getConfig() {
     if (!globalConfig) {

package/dist/cookie-pool.d.ts

@@ -3,7 +3,18 @@ export declare function selectAccountForRequest(): Promise<{
     accountId: string;
     cookies: LinkedInCookie[];
 }>;
+export declare function getAccountsSummary(): Array<{
+    accountId: string;
+    healthy: boolean;
+    failures: number;
+    cooldownUntil: number;
+    cooldownRemainingMs: number;
+    expiresAt?: number;
+    lastUsedAt?: number;
+}>;
 export declare function reportAccountFailure(accountId: string, isAuthError: boolean): void;
 export declare function reportAccountSuccess(accountId: string): void;
 export declare function buildCookieHeader(cookies: LinkedInCookie[]): string;
 export declare function extractCsrfToken(cookies: LinkedInCookie[]): string;
+export declare function adminSetCooldown(accountId: string, ms: number): void;
+export declare function adminResetAccount(accountId: string): void;

package/dist/cookie-pool.js

@@ -1,10 +1,13 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.selectAccountForRequest = selectAccountForRequest;
+exports.getAccountsSummary = getAccountsSummary;
 exports.reportAccountFailure = reportAccountFailure;
 exports.reportAccountSuccess = reportAccountSuccess;
 exports.buildCookieHeader = buildCookieHeader;
 exports.extractCsrfToken = extractCsrfToken;
+exports.adminSetCooldown = adminSetCooldown;
+exports.adminResetAccount = adminResetAccount;
 const cosiall_client_1 = require("./cosiall-client");
 const config_1 = require("./config");
 const errors_1 = require("./utils/errors");
@@ -23,11 +26,21 @@ function nowMs() {
 function nowSec() {
     return Math.floor(Date.now() / 1000);
 }
+function toEpochSeconds(v) {
+    if (typeof v !== 'number')
+        return undefined;
+    if (!Number.isFinite(v) || v <= 0)
+        return undefined;
+    // Treat large values as ms
+    return v > 1e10 ? Math.floor(v / 1000) : Math.floor(v);
+}
 function isExpired(entry) {
-    const jsession = entry.cookies.find(c => c.name.toUpperCase() === 'JSESSIONID');
-    if (typeof jsession?.expires === 'number' && jsession.expires < nowSec())
+    const jsession = entry.cookies.find(c => String(c.name).toUpperCase() === 'JSESSIONID');
+    const jsExp = toEpochSeconds(jsession?.expires);
+    if (jsExp && jsExp < nowSec())
         return true;
-    if (typeof entry.expiresAt === 'number' && entry.expiresAt < nowSec())
+    const accExp = toEpochSeconds(entry.expiresAt);
+    if (accExp && accExp < nowSec())
         return true;
     return false;
 }
@@ -44,6 +57,7 @@ async function ensureInitialized() {
             expiresAt: acc.expiresAt,
             failures: 0,
             cooldownUntil: 0,
+            lastUsedAt: undefined,
         });
         poolState.order.push(acc.accountId);
     }
@@ -66,6 +80,7 @@ async function ensureInitialized() {
                         expiresAt: acc.expiresAt,
                         failures: poolState.accounts.get(acc.accountId)?.failures ?? 0,
                         cooldownUntil: poolState.accounts.get(acc.accountId)?.cooldownUntil ?? 0,
+                        lastUsedAt: poolState.accounts.get(acc.accountId)?.lastUsedAt,
                     });
                     newOrder.push(acc.accountId);
                 }
@@ -74,7 +89,8 @@ async function ensureInitialized() {
                 (0, logger_1.log)('info', 'cookiePool.refreshed', { count: refreshed.length });
             }
             catch (e) {
-                (0, logger_1.log)('warn', 'cookiePool.refreshFailed', { error: e?.message });
+                const err = e;
+                (0, logger_1.log)('warn', 'cookiePool.refreshFailed', { error: err?.message });
             }
         }, interval);
     }
@@ -99,10 +115,33 @@ async function selectAccountForRequest() {
         poolState.rrIndex = (idx + 1) % n;
         (0, logger_1.log)('debug', 'cookiePool.select', { accountId: entry.accountId, rrIndex: poolState.rrIndex });
         (0, metrics_1.incrementMetric)('accountSelections');
+        entry.lastUsedAt = nowMs();
         return { accountId: entry.accountId, cookies: entry.cookies };
     }
     throw new errors_1.LinkedInClientError('No valid LinkedIn accounts', 'NO_VALID_ACCOUNTS', 503);
 }
+function getAccountsSummary() {
+    const now = nowMs();
+    const out = [];
+    for (const id of poolState.order) {
+        const entry = poolState.accounts.get(id);
+        if (!entry)
+            continue;
+        const expired = isExpired(entry);
+        const cooling = entry.cooldownUntil > now;
+        const healthy = !expired && !cooling && entry.failures === 0;
+        out.push({
+            accountId: entry.accountId,
+            healthy,
+            failures: entry.failures,
+            cooldownUntil: entry.cooldownUntil,
+            cooldownRemainingMs: Math.max(0, entry.cooldownUntil - now),
+            expiresAt: entry.expiresAt,
+            lastUsedAt: entry.lastUsedAt,
+        });
+    }
+    return out;
+}
 function reportAccountFailure(accountId, isAuthError) {
     const entry = poolState.accounts.get(accountId);
     if (!entry)
@@ -145,3 +184,17 @@ function getSettings() {
         return { cooldownMs: 5000, maxFailures: 3 };
     }
 }
+// Admin/dev helpers (no-ops if account missing). Safe to export for playground tooling.
+function adminSetCooldown(accountId, ms) {
+    const entry = poolState.accounts.get(accountId);
+    if (!entry)
+        return;
+    entry.cooldownUntil = nowMs() + Math.max(0, Number(ms || 0));
+}
+function adminResetAccount(accountId) {
+    const entry = poolState.accounts.get(accountId);
+    if (!entry)
+        return;
+    entry.failures = 0;
+    entry.cooldownUntil = 0;
+}

package/dist/cosiall-client.js

@@ -29,9 +29,24 @@ async function fetchCookiesFromCosiall() {
     }
     (0, logger_1.log)('info', 'cosiall.fetch.success', { count: data.length });
     (0, metrics_1.incrementMetric)('cosiallSuccess');
-    return data.map((item) => ({
-        accountId: item.accountId,
-        cookies: Array.isArray(item.cookies) ? item.cookies : [],
-        expiresAt: item.expiresAt,
-    }));
+    function isCookie(obj) {
+        return !!obj && typeof obj === 'object' && 'name' in obj && 'value' in obj;
+    }
+    function isItem(obj) {
+        if (!obj || typeof obj !== 'object')
+            return false;
+        const rec = obj;
+        if (typeof rec.accountId !== 'string')
+            return false;
+        if (!Array.isArray(rec.cookies))
+            return false;
+        if (!rec.cookies.every(isCookie))
+            return false;
+        if (rec.expiresAt !== undefined && typeof rec.expiresAt !== 'number')
+            return false;
+        return true;
+    }
+    return data
+        .filter(isItem)
+        .map((item) => ({ accountId: item.accountId, cookies: item.cookies, expiresAt: item.expiresAt }));
 }

package/dist/http-client.d.ts

@@ -1,7 +1,7 @@
 export interface LinkedInRequestOptions {
     url: string;
     method?: 'GET' | 'POST';
-    body?: any;
+    body?: unknown;
     headers?: Record<string, string>;
 }
 export declare function executeLinkedInRequest<T>(options: LinkedInRequestOptions, _operationName: string): Promise<T>;