linkedin-secret-sauce 0.1.1 → 0.1.2

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

@@ -21,6 +21,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 +30,7 @@ function initializeLinkedInClient(config) {
         accountCooldownMs: 5000,
         maxFailuresBeforeCooldown: 3,
         logLevel: 'info',
+        maxRequestHistory: 500,
         ...config,
     };
     // Optionally mask API key from accidental JSON serialization
@@ -42,7 +45,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);
                 }
@@ -99,10 +114,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 +183,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/http-client.js

@@ -6,6 +6,8 @@ const cookie_pool_1 = require("./cookie-pool");
 const errors_1 = require("./utils/errors");
 const logger_1 = require("./utils/logger");
 const metrics_1 = require("./utils/metrics");
+const request_history_1 = require("./utils/request-history");
+const linkedin_config_1 = require("./utils/linkedin-config");
 function sleep(ms) {
     return new Promise((resolve) => setTimeout(resolve, ms));
 }
@@ -14,6 +16,7 @@ function isRetryableStatus(status) {
 }
 async function executeLinkedInRequest(options, _operationName) {
     const config = (0, config_1.getConfig)();
+    const op = _operationName || 'request';
     const perAccountAttempts = (config.maxRetries ?? 0) + 1;
     const delay = config.retryDelayMs ?? 700;
     // Setup proxy env if configured
@@ -22,13 +25,11 @@ async function executeLinkedInRequest(options, _operationName) {
     let proxySet = false;
     try {
         if (config.proxyString) {
-            const [host, port, user, pass] = config.proxyString.split(":");
-            const proxyUrl = user && pass
-                ? `http://${user}:${pass}@${host}:${port}`
-                : `http://${host}:${port}`;
+            const { url: proxyUrl, masked } = parseProxyString(config.proxyString);
             process.env.HTTP_PROXY = proxyUrl;
             process.env.HTTPS_PROXY = proxyUrl;
             proxySet = true;
+            (0, logger_1.log)('info', 'proxy.set', { host: masked });
         }
         // Try up to 3 different accounts on auth/rate failures
         let lastError;
@@ -55,18 +56,38 @@ async function executeLinkedInRequest(options, _operationName) {
             const { accountId, cookies } = selection;
             const csrf = (0, cookie_pool_1.extractCsrfToken)(cookies);
             const cookieHeader = (0, cookie_pool_1.buildCookieHeader)(cookies);
+            // Choose header profile based on Sales vs Voyager context
+            const isSales = /\/sales\//i.test(String(options.headers?.Referer || ''))
+                || /https:\/\/www\.linkedin\.com\/sales-api/i.test(options.url);
+            const baseHeaders = isSales
+                ? (0, linkedin_config_1.buildSalesHeaders)({ cookiesHeader: cookieHeader, csrf, referer: options.headers?.Referer })
+                : (0, linkedin_config_1.buildVoyagerHeaders)({ cookiesHeader: cookieHeader, csrf, referer: options.headers?.Referer });
             const headers = {
-                Cookie: cookieHeader,
-                'csrf-token': csrf,
+                ...baseHeaders,
                 ...(options.headers || {}),
             };
             for (let attempt = 0; attempt < perAccountAttempts; attempt++) {
-                (0, logger_1.log)('debug', 'http.attempt', { accountId, attempt: attempt + 1, url: options.url });
-                const res = await fetch(options.url, {
-                    method: options.method ?? 'GET',
-                    headers,
-                    body: options.body ? JSON.stringify(options.body) : undefined,
-                });
+                const started = Date.now();
+                (0, logger_1.log)('debug', 'http.attempt', { accountId, attempt: attempt + 1, method: options.method ?? 'GET', url: options.url });
+                let res;
+                try {
+                    res = await fetch(options.url, {
+                        method: options.method ?? 'GET',
+                        headers,
+                        body: options.body ? JSON.stringify(options.body) : undefined,
+                    });
+                }
+                catch (err) {
+                    const code = err?.code || err?.cause?.code || 'FETCH_FAILED';
+                    (0, logger_1.log)('error', 'http.networkError', { accountId, url: options.url, code, message: String(err?.message || err) });
+                    (0, metrics_1.incrementMetric)('httpFailures');
+                    try {
+                        (0, request_history_1.recordRequest)({ operation: op, selector: options.url, status: 0, durationMs: Date.now() - started, accountId, errorMessage: String(err?.message || err) });
+                    }
+                    catch { }
+                    lastError = new errors_1.LinkedInClientError('LinkedIn fetch failed', 'REQUEST_FAILED', 0, accountId);
+                    break; // rotate to next account
+                }
                 if (res.ok) {
                     // success
                     try {
@@ -75,6 +96,16 @@ async function executeLinkedInRequest(options, _operationName) {
                     catch { }
                     (0, logger_1.log)('info', 'http.success', { accountId, url: options.url });
                     (0, metrics_1.incrementMetric)('httpSuccess');
+                    try {
+                        (0, request_history_1.recordRequest)({
+                            operation: op,
+                            selector: options.url,
+                            status: res.status ?? 200,
+                            durationMs: Date.now() - started,
+                            accountId,
+                        });
+                    }
+                    catch { }
                     return (await res.json());
                 }
                 const status = res.status ?? 0;
@@ -86,18 +117,44 @@ async function executeLinkedInRequest(options, _operationName) {
                     catch { }
                     (0, logger_1.log)('warn', 'http.rotateOnAuth', { accountId, status });
                     (0, metrics_1.incrementMetric)('authErrors');
+                    (0, metrics_1.incrementMetric)('httpFailures');
                     lastError = new errors_1.LinkedInClientError(`LinkedIn request failed: ${status}`, 'REQUEST_FAILED', status, accountId);
+                    try {
+                        (0, request_history_1.recordRequest)({
+                            operation: op,
+                            selector: options.url,
+                            status,
+                            durationMs: Date.now() - started,
+                            accountId,
+                            errorMessage: 'rotate',
+                        });
+                    }
+                    catch { }
                     break; // break inner loop to rotate account
                 }
                 // Retryable 5xx on same account
                 if ((status >= 500 && status < 600) && attempt < perAccountAttempts - 1) {
-                    (0, logger_1.log)('debug', 'http.retry', { accountId, status, nextDelayMs: delay });
+                    (0, logger_1.log)('debug', 'http.retry', { accountId, status, attempt: attempt + 1, nextDelayMs: delay });
                     (0, metrics_1.incrementMetric)('httpRetries');
                     await sleep(delay);
                     continue;
                 }
                 // Non-retryable: throw
-                throw new errors_1.LinkedInClientError(`LinkedIn request failed: ${status}`, 'REQUEST_FAILED', status, accountId);
+                const err = new errors_1.LinkedInClientError(`LinkedIn request failed: ${status}`, 'REQUEST_FAILED', status, accountId);
+                (0, metrics_1.incrementMetric)('httpFailures');
+                (0, logger_1.log)(status >= 500 ? 'warn' : 'error', 'http.fail', { accountId, status, url: options.url });
+                try {
+                    (0, request_history_1.recordRequest)({
+                        operation: op,
+                        selector: options.url,
+                        status,
+                        durationMs: Date.now() - started,
+                        accountId,
+                        errorMessage: err.message,
+                    });
+                }
+                catch { }
+                throw err;
             }
         }
         // Exhausted rotations
@@ -116,6 +173,51 @@ async function executeLinkedInRequest(options, _operationName) {
                 delete process.env.HTTPS_PROXY;
             else
                 process.env.HTTPS_PROXY = prevHttps;
+            (0, logger_1.log)('info', 'proxy.restore', {});
         }
     }
 }
+// Parse proxy string supporting:
+// - Full URL forms: http(s)://[user[:pass]@]host:port (host may be [ipv6])
+// - Colon-delimited: host:port[:user:pass] with optional [ipv6]
+function parseProxyString(input) {
+    const s = String(input).trim();
+    // URL form
+    if (/^\w+:\/\//.test(s)) {
+        try {
+            const u = new URL(s);
+            if (u.protocol !== 'http:' && u.protocol !== 'https:') {
+                throw new errors_1.LinkedInClientError(`Unsupported proxy protocol: ${u.protocol}`, 'INVALID_CONFIG', 400);
+            }
+            const user = u.username || '';
+            const pass = u.password || '';
+            const hostport = u.host; // includes brackets for IPv6
+            const url = `${u.protocol}//${user ? `${user}:${pass}@` : ''}${hostport}`;
+            const masked = user ? `${hostport}:${user}:***` : hostport;
+            return { url, masked };
+        }
+        catch {
+            // fall through to colon parsing
+        }
+    }
+    // Colon-delimited
+    // [ipv6]:port[:user:pass] OR host:port[:user:pass]
+    const m = s.match(/^(\[?[^\]]+\]?):(\d+)(?::([^:]*):(.+))?$/);
+    if (m) {
+        let host = m[1];
+        const port = m[2];
+        const user = m[3];
+        const pass = m[4];
+        // Ensure brackets for IPv6 in URL
+        const needsBrackets = host.includes(':') && !/^\[.*\]$/.test(host);
+        if (needsBrackets)
+            host = `[${host}]`;
+        const auth = user && pass ? `${user}:${pass}@` : '';
+        const url = `http://${auth}${host}:${port}`;
+        const hostport = `${host}:${port}`;
+        const masked = user && pass ? `${hostport}:${user}:***` : hostport;
+        return { url, masked };
+    }
+    // Fallback: conservative
+    return { url: s.includes('://') ? s : `http://${s}`, masked: '***' };
+}

package/dist/index.d.ts

@@ -8,3 +8,5 @@ export { parseSalesSearchResults } from './parsers/search-parser';
 export * from './linkedin-api';
 export * from './types';
 export * from './utils/metrics';
+export { getRequestHistory, clearRequestHistory } from './utils/request-history';
+export type { RequestHistoryEntry } from './utils/request-history';