linkedin-secret-sauce 0.10.1 → 0.11.1

package/README.md

@@ -1,277 +1,557 @@
-# LinkedIn Secret Sauce Client
+# LinkedIn Secret Sauce
 
-Private, server-side LinkedIn Sales Navigator client. It manages cookies/accounts, retries, caching, and parsing so your app calls a small, typed API.
+A complete LinkedIn Sales Navigator client + Email Enrichment library for Node.js/TypeScript.
 
-For a step‑by‑step integration guide you can copy/paste into other apps, see `docs/INTEGRATION.md`.
+**Two main modules:**
+1. **LinkedIn API** - Sales Navigator search, profiles, companies with automatic cookie/account rotation
+2. **Email Enrichment** - Find business emails via multiple providers (Hunter, Apollo, Bouncer, Snov.io, etc.)
 
-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.
+## Documentation
 
-- Node: >= 18 (uses global `fetch`)
-- Build: `pnpm build`
-- Test: `pnpm test`
+- [Full API Documentation](https://enerage.github.io/LinkedInSecretSauce/) - Auto-generated TypeDoc
+- [Integration Guide](docs/INTEGRATION.md) - Step-by-step setup
+- [Sales Search Guide](docs/SALES_SEARCH.md) - Advanced search filters
+- [Playground Guide](docs/PLAYGROUND.md) - Local dev UI
 
-## Install
+## Installation
 
 ```bash
-# pnpm (recommended)
 pnpm add linkedin-secret-sauce
-
-# npm
+# or
 npm install linkedin-secret-sauce
 ```
 
-## Quick Start
+**Requirements:** Node.js >= 18 (uses native fetch)
+
+---
+
+## Module 1: LinkedIn API
+
+Server-side LinkedIn Sales Navigator client with automatic cookie management, retries, caching, and parsing.
 
-```ts
+### Quick Start
+
+```typescript
 import {
   initializeLinkedInClient,
   getProfileByVanity,
-  getProfileByUrn,
   searchSalesLeads,
-  resolveCompanyUniversalName,
   getCompanyById,
-  getCompanyByUrl,
   typeahead,
-  getSalesNavigatorProfileDetails,
-  type LinkedInProfile,
-  type SearchSalesResult,
-  type Company,
-  type TypeaheadResult,
-  type SalesNavigatorProfile,
 } from 'linkedin-secret-sauce';
 
+// Initialize once at app startup
 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',
+  logLevel: 'info',
 });
 
-const prof: LinkedInProfile = await getProfileByVanity('john-doe');
-const prof2 = await getProfileByUrn('urn:li:fsd_profile:ACwAAAbCdEf'); // URN or bare key
+// Fetch a profile
+const profile = await getProfileByVanity('john-doe');
+console.log(profile.firstName, profile.lastName);
+console.log(profile.positions); // Work history
 
-// Search with paging; uses LeadSearchResult-14 for complete profile data (positions, badges, etc.)
-const leads: SearchSalesResult = await searchSalesLeads('cto fintech', { start: 50, count: 10 });
+// Search Sales Navigator
+const results = await searchSalesLeads('cto fintech', { start: 0, count: 25 });
+for (const lead of results.items) {
+  console.log(lead.fullName, lead.title, lead.company);
+}
+
+// Get company details
+const company = await getCompanyById(1234567);
+console.log(company.name, company.industry, company.employeeCount);
+```
+
+### Configuration
+
+| Variable | Required | Description |
+|----------|----------|-------------|
+| `COSIALL_API_URL` | Yes | Base URL of your Cosiall cookie service |
+| `COSIALL_API_KEY` | Yes | API key for Cosiall |
+| `LINKEDIN_PROXY_STRING` | No | Proxy in format `host:port` or `host:port:user:pass` |
+| `LOG_LEVEL` | No | `debug`, `info`, `warn`, `error` (default: `info`) |
+
+### API Reference
+
+#### Profiles
+```typescript
+// By vanity URL (username)
+const profile = await getProfileByVanity('john-doe');
+
+// By URN or key
+const profile = await getProfileByUrn('urn:li:fsd_profile:ACwAAAbCdEf');
+const profile = await getProfileByUrn('ACwAAAbCdEf'); // Just the key works too
+
+// Batch fetch (parallel with concurrency control)
+const profiles = await getProfilesBatch(['john-doe', 'jane-smith'], 5);
+```
 
-// Companies
+#### Search
+```typescript
+// Basic keyword search
+const results = await searchSalesLeads('software engineer');
+
+// With pagination
+const results = await searchSalesLeads('cto fintech', { 
+  start: 0,    // Offset
+  count: 25    // Results per page (max 100)
+});
+
+// Access results
+results.items.forEach(lead => {
+  console.log(lead.fullName);
+  console.log(lead.title);
+  console.log(lead.company);
+  console.log(lead.linkedInUrl);
+  console.log(lead.fsdKey); // Use for detailed profile fetch
+});
+```
+
+#### Companies
+```typescript
+// Resolve company name to ID
 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 });
+// Get company details
+const company = await getCompanyById(companyId);
+console.log(company.name, company.website, company.employeeCount);
+
+// From LinkedIn URL
+const company = await getCompanyByUrl('https://linkedin.com/company/microsoft/');
+```
+
+#### Typeahead (Autocomplete)
+```typescript
+// Geographic locations
+const locations = await typeahead({ 
+  type: 'BING_GEO', 
+  query: 'new york',
+  count: 10 
+});
 
-// Sales Navigator profile details
-const sales: SalesNavigatorProfile = await getSalesNavigatorProfileDetails('urn:li:fs_salesProfile:ACwAAA...');
+// Industries, titles, companies also supported
 ```
 
-## Environment & Config
-
-Required
-- `COSIALL_API_URL` – base URL of your Cosiall service (e.g., https://cosiall.example)
-- `COSIALL_API_KEY` – API key for the Cosiall endpoint
-
-Optional
-- `LINKEDIN_PROXY_STRING` – `host:port` or `host:port:user:pass`
-- `LOG_LEVEL` – `debug` | `info` | `warn` | `error` (default `info`)
-
-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
-
-## Public API (overview)
-
-- 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.
-
-- Search
-  - `searchSalesLeads(keywords, { start, count, decorationId })` – when options are provided returns `{ items, page }`; uses LeadSearchResult-14 by default for complete profile data.
-
-- Companies
-  - `resolveCompanyUniversalName(universalName)` → `{ companyId? }` (404 → NOT_FOUND)
-  - `getCompanyById(companyId)` → `Company` (10m cache)
-  - `getCompanyByUrl(url)` – parses numeric id or slug, then fetches
-
-- 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`
-
-## Caching, Metrics, Proxy
-
-- 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`).
-
-### 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,
-//   ...
-// }
+### Error Handling
+
+```typescript
+import { LinkedInClientError } from 'linkedin-secret-sauce';
+
+try {
+  const profile = await getProfileByVanity('nonexistent');
+} catch (error) {
+  if (error instanceof LinkedInClientError) {
+    switch (error.code) {
+      case 'NOT_FOUND':
+        console.log('Profile does not exist');
+        break;
+      case 'RATE_LIMITED':
+        console.log('Too many requests, wait before retrying');
+        break;
+      case 'AUTH_ERROR':
+        console.log('Cookie/session expired');
+        break;
+    }
+  }
+}
 ```
 
-### Accounts Summary
+### Metrics & Monitoring
 
-```ts
-import { getAccountsSummary } from 'linkedin-secret-sauce';
+```typescript
+import { 
+  getSnapshot,
+  getRequestHistory,
+  getAccountsSummary 
+} from 'linkedin-secret-sauce';
 
+// Performance metrics
+const metrics = getSnapshot();
+console.log(metrics.profileFetches);
+console.log(metrics.httpSuccess);
+console.log(metrics.cacheHits);
+
+// Request log (bounded, for debugging)
+const history = getRequestHistory();
+
+// Account health status
 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
-//   }
-// ]
+accounts.forEach(acc => {
+  console.log(`${acc.accountId}: healthy=${acc.healthy}`);
+});
 ```
 
-## Testing
+---
+
+## Module 2: Email Enrichment
+
+Find and verify business emails using multiple providers with waterfall/parallel strategies.
+
+### Supported Providers
+
+| Provider | Type | Cost | Best For |
+|----------|------|------|----------|
+| **Construct** | Pattern + MX | FREE | Quick pattern matching |
+| **LDD** | Database | FREE | LinkedIn profile emails |
+| **Bouncer** | SMTP Verify | $0.006/email | Catch-all detection, 99%+ accuracy |
+| **Snov.io** | Email Finder | $0.02/email | Finding emails by name+domain |
+| **Hunter** | Email Finder | $0.005/email | Domain search, email finder |
+| **Apollo** | Database | FREE | B2B contact database |
+| **SmartProspect** | Database | $0.01/email | Lead database search |
+
+### Quick Start
+
+```typescript
+import { createEnrichmentClient } from 'linkedin-secret-sauce';
+
+const enrichment = createEnrichmentClient({
+  providers: {
+    // FREE providers (no API key needed)
+    construct: {},
+    
+    // Paid providers (add your API keys)
+    hunter: { apiKey: process.env.HUNTER_API_KEY },
+    apollo: { apiKey: process.env.APOLLO_API_KEY },
+    bouncer: { apiKey: process.env.BOUNCER_API_KEY },
+    snovio: { 
+      clientId: process.env.SNOVIO_CLIENT_ID,
+      clientSecret: process.env.SNOVIO_CLIENT_SECRET 
+    },
+    
+    // Your private LinkedIn data dump
+    ldd: { 
+      apiUrl: process.env.LDD_API_URL,
+      apiToken: process.env.LDD_API_TOKEN 
+    },
+    
+    // SmartLead (supports credentials or direct token)
+    smartprospect: {
+      email: process.env.SMARTLEAD_EMAIL,
+      password: process.env.SMARTLEAD_PASSWORD,
+    },
+  },
+  
+  // Optional: cost tracking callback
+  onCost: (provider, cost) => {
+    console.log(`${provider} cost: $${cost}`);
+  },
+});
+
+// Find business email for a person
+const result = await enrichment.enrich({
+  firstName: 'John',
+  lastName: 'Doe',
+  company: 'Acme Corp',
+  domain: 'acme.com',          // Optional but improves accuracy
+  linkedinUrl: 'linkedin.com/in/johndoe', // For LDD lookups
+});
+
+console.log(result.business_email);        // john.doe@acme.com
+console.log(result.business_email_source); // 'hunter'
+console.log(result.business_email_verified); // true
+console.log(result.business_email_confidence); // 95
+```
+
+### Batch Processing
+
+```typescript
+// Process multiple candidates efficiently
+const candidates = [
+  { firstName: 'John', lastName: 'Doe', domain: 'acme.com' },
+  { firstName: 'Jane', lastName: 'Smith', domain: 'techcorp.io' },
+  // ... hundreds more
+];
+
+const results = await enrichment.enrichBatch(candidates, {
+  batchSize: 50,   // Process 50 at a time
+  delayMs: 200,    // Delay between batches (rate limiting)
+});
+
+results.forEach(r => {
+  console.log(`${r.candidate.firstName}: ${r.business_email}`);
+});
+```
+
+### Get ALL Emails (Multi-Provider)
+
+```typescript
+// Get emails from ALL providers instead of stopping at first match
+const result = await enrichment.enrichAll({
+  firstName: 'John',
+  lastName: 'Doe',
+  domain: 'acme.com',
+});
+
+// Returns all found emails sorted by confidence
+result.emails.forEach(email => {
+  console.log(email.email);       // john.doe@acme.com
+  console.log(email.source);      // 'hunter'
+  console.log(email.confidence);  // 95
+  console.log(email.verified);    // true
+  console.log(email.type);        // 'business'
+});
+
+console.log(result.totalCost);    // Total $ spent across providers
+console.log(result.providersQueried); // ['construct', 'hunter', 'apollo']
+```
+
+### Email Verification with Bouncer
+
+```typescript
+import { 
+  verifyEmailWithBouncer,
+  checkCatchAllDomain,
+  verifyEmailsBatch 
+} from 'linkedin-secret-sauce';
+
+// Verify a single email
+const verification = await verifyEmailWithBouncer(
+  'john@example.com',
+  { apiKey: process.env.BOUNCER_API_KEY }
+);
+
+console.log(verification.status);    // 'deliverable' | 'undeliverable' | 'risky'
+console.log(verification.reason);    // 'accepted_email' | 'rejected_email' | etc
+console.log(verification.acceptAll); // true = catch-all domain (can't verify)
+console.log(verification.disposable); // Is this a temp email?
+console.log(verification.role);      // Is this info@, support@, etc?
+
+// Check if domain is catch-all (accepts any email)
+const isCatchAll = await checkCatchAllDomain('example.com', config);
+if (isCatchAll) {
+  console.log('Cannot verify emails - domain accepts everything');
+}
+
+// Batch verify (with concurrency control)
+const results = await verifyEmailsBatch(
+  ['john@example.com', 'jane@example.com'],
+  { apiKey: process.env.BOUNCER_API_KEY }
+);
+```
+
+### Email Finding with Snov.io
+
+```typescript
+import { 
+  findEmailsWithSnovio,
+  verifyEmailWithSnovio 
+} from 'linkedin-secret-sauce';
+
+// Find emails for a person
+const emails = await findEmailsWithSnovio(
+  'John',
+  'Doe', 
+  'acme.com',
+  { 
+    clientId: process.env.SNOVIO_CLIENT_ID,
+    clientSecret: process.env.SNOVIO_CLIENT_SECRET 
+  }
+);
+
+emails?.emails.forEach(e => {
+  console.log(e.email, e.emailStatus);
+});
+```
+
+### Email Validation Utilities
+
+```typescript
+import {
+  isValidEmailSyntax,
+  isPersonalEmail,
+  isBusinessEmail,
+  isDisposableEmail,
+  isRoleAccount,
+  PERSONAL_DOMAINS,
+  DISPOSABLE_DOMAINS,
+} from 'linkedin-secret-sauce';
+
+// Syntax validation
+isValidEmailSyntax('john@example.com'); // true
+isValidEmailSyntax('invalid');          // false
+
+// Domain classification
+isPersonalEmail('john@gmail.com');      // true (Gmail, Yahoo, etc.)
+isBusinessEmail('john@acme.com');       // true (not personal domain)
+isDisposableEmail('x@mailinator.com');  // true (temp email service)
+
+// Role account detection (info@, support@, etc.)
+isRoleAccount('info@company.com');      // true
+isRoleAccount('john@company.com');      // false
+
+// Access domain lists directly
+console.log(PERSONAL_DOMAINS.has('gmail.com'));  // true
+console.log(DISPOSABLE_DOMAINS.size);            // 500+ domains
+```
+
+### Custom Provider Order
+
+```typescript
+const enrichment = createEnrichmentClient({
+  providers: { /* ... */ },
+  options: {
+    // Custom order - cheaper/faster providers first
+    providerOrder: [
+      'construct',    // FREE - pattern matching
+      'ldd',          // FREE - your database
+      'apollo',       // FREE - limited quota
+      'hunter',       // $0.005
+      'bouncer',      // $0.006 (verification only)
+      'smartprospect', // $0.01
+      'snovio',       // $0.02
+    ],
+    
+    // Stop after finding one verified email
+    stopOnFirstVerified: true,
+    
+    // Minimum confidence to accept
+    minConfidence: 70,
+  },
+});
+```
+
+### Caching
+
+```typescript
+const enrichment = createEnrichmentClient({
+  providers: { /* ... */ },
+  
+  // Optional cache implementation
+  cache: {
+    async get(key: string) {
+      return redis.get(key);
+    },
+    async set(key: string, value: any, ttlMs?: number) {
+      await redis.set(key, value, 'PX', ttlMs || 86400000);
+    },
+  },
+});
+```
+
+---
+
+## Combined Workflow Example
+
+Here's a complete example: Search LinkedIn -> Enrich with emails:
+
+```typescript
+import {
+  initializeLinkedInClient,
+  searchSalesLeads,
+  getProfileByUrn,
+  createEnrichmentClient,
+} from 'linkedin-secret-sauce';
+
+// Initialize LinkedIn client
+initializeLinkedInClient({
+  cosiallApiUrl: process.env.COSIALL_API_URL!,
+  cosiallApiKey: process.env.COSIALL_API_KEY!,
+});
+
+// Initialize enrichment client
+const enrichment = createEnrichmentClient({
+  providers: {
+    construct: {},
+    hunter: { apiKey: process.env.HUNTER_API_KEY },
+    bouncer: { apiKey: process.env.BOUNCER_API_KEY },
+  },
+});
+
+async function findLeadsWithEmails(query: string, limit: number) {
+  // Step 1: Search LinkedIn
+  const searchResults = await searchSalesLeads(query, { count: limit });
+  
+  const enrichedLeads = [];
+  
+  for (const lead of searchResults.items) {
+    // Step 2: Get full profile (optional, for more data)
+    const profile = lead.fsdKey 
+      ? await getProfileByUrn(lead.fsdKey)
+      : null;
+    
+    // Step 3: Find business email
+    const emailResult = await enrichment.enrich({
+      firstName: lead.firstName,
+      lastName: lead.lastName,
+      company: lead.company,
+      domain: profile?.company?.domain, // If available
+      linkedinUrl: lead.linkedInUrl,
+    });
+    
+    enrichedLeads.push({
+      name: lead.fullName,
+      title: lead.title,
+      company: lead.company,
+      linkedIn: lead.linkedInUrl,
+      email: emailResult.business_email,
+      emailVerified: emailResult.business_email_verified,
+    });
+  }
+  
+  return enrichedLeads;
+}
+
+// Usage
+const leads = await findLeadsWithEmails('cto fintech san francisco', 50);
+console.table(leads);
+```
+
+---
+
+## Development
 
 ```bash
+# Install dependencies
+pnpm install
+
+# Build
+pnpm build
+
+# Run tests
 pnpm test
-pnpm exec tsc -p tsconfig.json --noEmit
+
+# Type check
+pnpm typecheck
+
+# Lint
+pnpm lint
+
+# Generate documentation
+pnpm docs
+```
+
+### Playground (Dev UI)
+
+```bash
+pnpm dev:playground
+```
+
+Opens a React UI at http://localhost:5173 to test the API interactively.
+
+---
+
+## Publishing
+
+```bash
+# Bump version
+npm version patch  # or minor/major
+
+# Publish to npm
+npm publish
+
+# Push tags
+git push --follow-tags
 ```
 
-## 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.
-
-## Changelog
-
-See [CHANGELOG.md](CHANGELOG.md) for release notes and upgrade guides.
-
-**Latest:** v0.3.10 - Fixed `fsdKey` extraction from Sales Navigator URNs
-
-## Known Issues & Solutions
-
-### Sales Navigator Search Results
-
-**Issue:** `fsdKey` field not populated in search results (fixed in v0.3.10)
-
-If you're on an older version, you may need to manually extract `fsdKey`:
-```typescript
-const results = await searchSalesLeads('query');
-// For older versions (<0.3.10), fsdKey might be missing
-// Solution: Update to v0.3.10+
-```
-
-**Upgrade:**
-```bash
-npm update linkedin-secret-sauce
-# or
-pnpm update linkedin-secret-sauce
-```
-
-After upgrading to v0.3.10+, `fsdKey` will be correctly populated from URNs like:
-```
-urn:li:fs_salesProfile:(ACwAAAAM3xgBU8jQ8zPMpR_WswldHDbBxoOu6p8,NAME_SEARCH,g2em)
-```
-
-### Profile Enrichment Pattern
-
-For best results, use this two-step pattern:
-
-```typescript
-// Step 1: Search (lightweight, returns many results quickly)
-const searchResults = await searchSalesLeads('software engineer berlin');
-
-// Step 2: Enrich selected results (slower, returns full data)
-for (const result of searchResults.items) {
-  if (result.fsdKey) {
-    const fullProfile = await getProfileByUrn(result.fsdKey);
-    // Now you have positions[] and educations[] arrays
-    console.log(`${fullProfile.firstName} has ${fullProfile.positions.length} jobs`);
-  }
-}
-```
-
-
-## 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.
+---
+
+## License
+
+UNLICENSED - Private package
+
+## Support
+
+- Issues: [GitHub Issues](https://github.com/enerage/LinkedInSecretSauce/issues)
+- Docs: [API Documentation](https://enerage.github.io/LinkedInSecretSauce/)