linkedin-secret-sauce 0.12.1 → 0.12.3

package/dist/utils/lru-cache.d.ts

@@ -0,0 +1,105 @@
+/**
+ * Simple LRU (Least Recently Used) Cache
+ *
+ * A memory-bounded cache that evicts the least recently used entries
+ * when the maximum size is exceeded. Prevents unbounded memory growth.
+ *
+ * Features:
+ * - O(1) get and set operations
+ * - Automatic eviction of stale entries
+ * - Optional TTL support
+ * - Size limit enforcement
+ */
+/**
+ * Cache entry with data and timestamp
+ */
+export interface CacheEntry<T> {
+    data: T;
+    ts: number;
+}
+/**
+ * LRU Cache implementation using Map's insertion order
+ *
+ * JavaScript Map maintains insertion order, so we can implement LRU
+ * by deleting and re-inserting on access (moving to end).
+ */
+export declare class LRUCache<T> {
+    private cache;
+    private readonly maxSize;
+    private readonly ttlMs;
+    /**
+     * Create a new LRU cache
+     *
+     * @param maxSize - Maximum number of entries to store (default: 1000)
+     * @param ttlMs - Optional TTL in milliseconds (default: null = no expiry)
+     */
+    constructor(maxSize?: number, ttlMs?: number | null);
+    /**
+     * Get a value from the cache
+     *
+     * @param key - Cache key
+     * @param ttlOverride - Optional TTL override in milliseconds (for dynamic TTL from config)
+     * @returns The cached value or null if not found/expired
+     */
+    get(key: string, ttlOverride?: number): T | null;
+    /**
+     * Set a value in the cache
+     *
+     * @param key - Cache key
+     * @param data - Value to cache
+     */
+    set(key: string, data: T): void;
+    /**
+     * Delete a key from the cache
+     *
+     * @param key - Cache key to delete
+     * @returns true if the key existed
+     */
+    delete(key: string): boolean;
+    /**
+     * Check if a key exists in the cache (without updating access time)
+     *
+     * @param key - Cache key
+     * @returns true if key exists and is not expired
+     */
+    has(key: string): boolean;
+    /**
+     * Clear all entries from the cache
+     */
+    clear(): void;
+    /**
+     * Get the current number of entries in the cache
+     */
+    get size(): number;
+    /**
+     * Get all keys in the cache (for debugging/testing)
+     */
+    keys(): IterableIterator<string>;
+    /**
+     * Prune expired entries (useful for periodic cleanup)
+     *
+     * @returns Number of entries removed
+     */
+    prune(): number;
+    /**
+     * Get cache statistics
+     */
+    stats(): {
+        size: number;
+        maxSize: number;
+        ttlMs: number | null;
+    };
+}
+/**
+ * Create a new LRU cache with the specified options
+ *
+ * @example
+ * ```typescript
+ * // Cache up to 500 profiles for 15 minutes
+ * const profileCache = createLRUCache<LinkedInProfile>(500, 15 * 60 * 1000);
+ *
+ * profileCache.set('johndoe', profile);
+ * const cached = profileCache.get('johndoe');
+ * ```
+ */
+export declare function createLRUCache<T>(maxSize?: number, ttlMs?: number | null): LRUCache<T>;

package/dist/utils/lru-cache.js

@@ -0,0 +1,175 @@
+"use strict";
+/**
+ * Simple LRU (Least Recently Used) Cache
+ *
+ * A memory-bounded cache that evicts the least recently used entries
+ * when the maximum size is exceeded. Prevents unbounded memory growth.
+ *
+ * Features:
+ * - O(1) get and set operations
+ * - Automatic eviction of stale entries
+ * - Optional TTL support
+ * - Size limit enforcement
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.LRUCache = void 0;
+exports.createLRUCache = createLRUCache;
+/**
+ * LRU Cache implementation using Map's insertion order
+ *
+ * JavaScript Map maintains insertion order, so we can implement LRU
+ * by deleting and re-inserting on access (moving to end).
+ */
+class LRUCache {
+    cache;
+    maxSize;
+    ttlMs;
+    /**
+     * Create a new LRU cache
+     *
+     * @param maxSize - Maximum number of entries to store (default: 1000)
+     * @param ttlMs - Optional TTL in milliseconds (default: null = no expiry)
+     */
+    constructor(maxSize = 1000, ttlMs = null) {
+        this.cache = new Map();
+        this.maxSize = maxSize;
+        this.ttlMs = ttlMs;
+    }
+    /**
+     * Get a value from the cache
+     *
+     * @param key - Cache key
+     * @param ttlOverride - Optional TTL override in milliseconds (for dynamic TTL from config)
+     * @returns The cached value or null if not found/expired
+     */
+    get(key, ttlOverride) {
+        const entry = this.cache.get(key);
+        if (!entry) {
+            return null;
+        }
+        // Check TTL expiration (use override if provided, otherwise instance TTL)
+        const effectiveTtl = ttlOverride ?? this.ttlMs;
+        if (effectiveTtl !== null && Date.now() - entry.ts > effectiveTtl) {
+            this.cache.delete(key);
+            return null;
+        }
+        // Move to end (most recently used) by delete + set
+        this.cache.delete(key);
+        this.cache.set(key, entry);
+        return entry.data;
+    }
+    /**
+     * Set a value in the cache
+     *
+     * @param key - Cache key
+     * @param data - Value to cache
+     */
+    set(key, data) {
+        // If key exists, delete it first (will be re-added at end)
+        if (this.cache.has(key)) {
+            this.cache.delete(key);
+        }
+        // Evict oldest entries if at capacity
+        while (this.cache.size >= this.maxSize) {
+            const oldestKey = this.cache.keys().next().value;
+            if (oldestKey !== undefined) {
+                this.cache.delete(oldestKey);
+            }
+            else {
+                break;
+            }
+        }
+        // Add new entry
+        this.cache.set(key, { data, ts: Date.now() });
+    }
+    /**
+     * Delete a key from the cache
+     *
+     * @param key - Cache key to delete
+     * @returns true if the key existed
+     */
+    delete(key) {
+        return this.cache.delete(key);
+    }
+    /**
+     * Check if a key exists in the cache (without updating access time)
+     *
+     * @param key - Cache key
+     * @returns true if key exists and is not expired
+     */
+    has(key) {
+        const entry = this.cache.get(key);
+        if (!entry) {
+            return false;
+        }
+        // Check TTL expiration
+        if (this.ttlMs !== null && Date.now() - entry.ts > this.ttlMs) {
+            this.cache.delete(key);
+            return false;
+        }
+        return true;
+    }
+    /**
+     * Clear all entries from the cache
+     */
+    clear() {
+        this.cache.clear();
+    }
+    /**
+     * Get the current number of entries in the cache
+     */
+    get size() {
+        return this.cache.size;
+    }
+    /**
+     * Get all keys in the cache (for debugging/testing)
+     */
+    keys() {
+        return this.cache.keys();
+    }
+    /**
+     * Prune expired entries (useful for periodic cleanup)
+     *
+     * @returns Number of entries removed
+     */
+    prune() {
+        if (this.ttlMs === null) {
+            return 0;
+        }
+        const now = Date.now();
+        let removed = 0;
+        for (const [key, entry] of this.cache) {
+            if (now - entry.ts > this.ttlMs) {
+                this.cache.delete(key);
+                removed++;
+            }
+        }
+        return removed;
+    }
+    /**
+     * Get cache statistics
+     */
+    stats() {
+        return {
+            size: this.cache.size,
+            maxSize: this.maxSize,
+            ttlMs: this.ttlMs,
+        };
+    }
+}
+exports.LRUCache = LRUCache;
+/**
+ * Create a new LRU cache with the specified options
+ *
+ * @example
+ * ```typescript
+ * // Cache up to 500 profiles for 15 minutes
+ * const profileCache = createLRUCache<LinkedInProfile>(500, 15 * 60 * 1000);
+ *
+ * profileCache.set('johndoe', profile);
+ * const cached = profileCache.get('johndoe');
+ * ```
+ */
+function createLRUCache(maxSize = 1000, ttlMs = null) {
+    return new LRUCache(maxSize, ttlMs);
+}

package/docs/COSIALL_PROFILE_EMAILS.md

@@ -0,0 +1,342 @@
+# Cosiall Profile Emails API
+
+This document describes how to use the Cosiall Profile Emails API to retrieve email addresses associated with LinkedIn profiles.
+
+## Overview
+
+The Profile Emails endpoint retrieves all email addresses associated with a LinkedIn profile from the Cosiall database. It provides flexible lookup options using ObjectURN, LinkedIn URL, or vanity name.
+
+## API Endpoint
+
+```
+GET /api/flexiq/profile-emails
+```
+
+### Authentication
+
+| Header | Value | Required |
+|--------|-------|----------|
+| `X-API-Key` | Your FlexIQ API key | Yes |
+
+### Query Parameters
+
+At least one of the following parameters must be provided:
+
+| Parameter | Type | Description | Example |
+|-----------|------|-------------|---------|
+| `objectUrn` | string | LinkedIn ObjectURN identifier | `urn:li:member:129147375` |
+| `linkedInUrl` | string | Full LinkedIn profile URL | `https://www.linkedin.com/in/john-doe/` |
+| `vanity` | string | LinkedIn username/vanity name | `john-doe` |
+
+**Priority**: If multiple parameters are provided, the lookup follows this order:
+1. `objectUrn` (most precise)
+2. `linkedInUrl`
+3. `vanity`
+
+### Response
+
+#### Success (200 OK)
+
+```json
+{
+  "profileId": 12345,
+  "objectUrn": "urn:li:member:129147375",
+  "linkedInUrl": "https://www.linkedin.com/in/john-doe/",
+  "emails": [
+    "john.doe@company.com",
+    "johndoe@gmail.com"
+  ]
+}
+```
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `profileId` | integer | Cosiall internal profile ID |
+| `objectUrn` | string | LinkedIn ObjectURN |
+| `linkedInUrl` | string | LinkedIn profile URL |
+| `emails` | array | List of email addresses (may be empty) |
+
+#### Error Responses
+
+| Status | Description | Response Body |
+|--------|-------------|---------------|
+| 400 Bad Request | No search parameters provided | `{ "error": "At least one of 'objectUrn', 'linkedInUrl', or 'vanity' must be provided." }` |
+| 401 Unauthorized | Invalid or missing API key | - |
+| 404 Not Found | Profile not found in database | `{ "error": "No LinkedIn profile found matching the provided parameters." }` |
+| 500 Internal Server Error | Server error | `{ "error": "An internal server error occurred while retrieving profile emails." }` |
+
+## Usage Examples
+
+### cURL
+
+**Using ObjectURN:**
+```bash
+curl -X GET "https://api.cosiall.com/api/flexiq/profile-emails?objectUrn=urn:li:member:129147375" \
+  -H "X-API-Key: your-api-key"
+```
+
+**Using LinkedIn URL:**
+```bash
+curl -X GET "https://api.cosiall.com/api/flexiq/profile-emails?linkedInUrl=https://www.linkedin.com/in/john-doe/" \
+  -H "X-API-Key: your-api-key"
+```
+
+**Using Vanity/Username:**
+```bash
+curl -X GET "https://api.cosiall.com/api/flexiq/profile-emails?vanity=john-doe" \
+  -H "X-API-Key: your-api-key"
+```
+
+### Python
+
+```python
+import requests
+
+API_KEY = "your-api-key"
+BASE_URL = "https://api.cosiall.com/api/flexiq"
+
+def get_profile_emails(object_urn=None, linkedin_url=None, vanity=None):
+    headers = {"X-API-Key": API_KEY}
+    params = {}
+    
+    if object_urn:
+        params["objectUrn"] = object_urn
+    if linkedin_url:
+        params["linkedInUrl"] = linkedin_url
+    if vanity:
+        params["vanity"] = vanity
+    
+    response = requests.get(f"{BASE_URL}/profile-emails", headers=headers, params=params)
+    
+    if response.status_code == 200:
+        return response.json()
+    elif response.status_code == 404:
+        return None  # Profile not found
+    else:
+        response.raise_for_status()
+
+# Usage examples
+emails_data = get_profile_emails(vanity="john-doe")
+if emails_data:
+    print(f"Found {len(emails_data['emails'])} email(s): {emails_data['emails']}")
+
+# Or by ObjectURN (most precise)
+emails_data = get_profile_emails(object_urn="urn:li:member:129147375")
+
+# Or by LinkedIn URL
+emails_data = get_profile_emails(linkedin_url="https://www.linkedin.com/in/john-doe/")
+```
+
+### JavaScript/Node.js
+
+```javascript
+const axios = require('axios');
+
+const API_KEY = 'your-api-key';
+const BASE_URL = 'https://api.cosiall.com/api/flexiq';
+
+async function getProfileEmails({ objectUrn, linkedInUrl, vanity }) {
+  try {
+    const response = await axios.get(`${BASE_URL}/profile-emails`, {
+      headers: { 'X-API-Key': API_KEY },
+      params: { objectUrn, linkedInUrl, vanity }
+    });
+    return response.data;
+  } catch (error) {
+    if (error.response?.status === 404) {
+      return null; // Profile not found
+    }
+    throw error;
+  }
+}
+
+// Usage examples
+const data = await getProfileEmails({ vanity: 'john-doe' });
+if (data) {
+  console.log(`Found ${data.emails.length} email(s):`, data.emails);
+}
+
+// Or by ObjectURN
+const dataByUrn = await getProfileEmails({ objectUrn: 'urn:li:member:129147375' });
+
+// Or by LinkedIn URL
+const dataByUrl = await getProfileEmails({ linkedInUrl: 'https://www.linkedin.com/in/john-doe/' });
+```
+
+### C#
+
+```csharp
+using System.Net.Http;
+using System.Text.Json;
+
+public class FlexIQClient
+{
+    private readonly HttpClient _client;
+    private const string BaseUrl = "https://api.cosiall.com/api/flexiq";
+
+    public FlexIQClient(string apiKey)
+    {
+        _client = new HttpClient();
+        _client.DefaultRequestHeaders.Add("X-API-Key", apiKey);
+    }
+
+    public async Task<ProfileEmailsResponse?> GetProfileEmailsAsync(
+        string? objectUrn = null,
+        string? linkedInUrl = null,
+        string? vanity = null)
+    {
+        var queryParams = new List<string>();
+        if (!string.IsNullOrEmpty(objectUrn))
+            queryParams.Add($"objectUrn={Uri.EscapeDataString(objectUrn)}");
+        if (!string.IsNullOrEmpty(linkedInUrl))
+            queryParams.Add($"linkedInUrl={Uri.EscapeDataString(linkedInUrl)}");
+        if (!string.IsNullOrEmpty(vanity))
+            queryParams.Add($"vanity={Uri.EscapeDataString(vanity)}");
+
+        var url = $"{BaseUrl}/profile-emails?{string.Join("&", queryParams)}";
+        var response = await _client.GetAsync(url);
+
+        if (response.StatusCode == System.Net.HttpStatusCode.NotFound)
+            return null;
+
+        response.EnsureSuccessStatusCode();
+        var json = await response.Content.ReadAsStringAsync();
+        return JsonSerializer.Deserialize<ProfileEmailsResponse>(json);
+    }
+}
+
+public class ProfileEmailsResponse
+{
+    public int ProfileId { get; set; }
+    public string? ObjectUrn { get; set; }
+    public string? LinkedInUrl { get; set; }
+    public List<string> Emails { get; set; } = new();
+}
+```
+
+## Using the LinkedIn Secret Sauce Library
+
+The library provides a convenient wrapper function for this endpoint.
+
+### Installation
+
+```bash
+npm install linkedin-secret-sauce
+# or
+pnpm add linkedin-secret-sauce
+```
+
+### Usage
+
+```typescript
+import { 
+  initializeLinkedInClient, 
+  fetchProfileEmailsFromCosiall 
+} from 'linkedin-secret-sauce';
+
+// Initialize the client (required once at startup)
+initializeLinkedInClient({
+  cosiallApiUrl: process.env.COSIALL_API_URL,
+  cosiallApiKey: process.env.COSIALL_API_KEY,
+});
+
+// Lookup by ObjectURN (most precise)
+const result = await fetchProfileEmailsFromCosiall({
+  objectUrn: 'urn:li:member:129147375'
+});
+
+// Lookup by LinkedIn URL
+const result = await fetchProfileEmailsFromCosiall({
+  linkedInUrl: 'https://www.linkedin.com/in/john-doe/'
+});
+
+// Lookup by vanity name
+const result = await fetchProfileEmailsFromCosiall({
+  vanity: 'john-doe'
+});
+
+console.log(`Profile ID: ${result.profileId}`);
+console.log(`Found ${result.emails.length} emails:`, result.emails);
+```
+
+### Error Handling
+
+```typescript
+import { 
+  fetchProfileEmailsFromCosiall, 
+  LinkedInClientError 
+} from 'linkedin-secret-sauce';
+
+try {
+  const result = await fetchProfileEmailsFromCosiall({ vanity: 'john-doe' });
+  console.log(result.emails);
+} catch (error) {
+  if (error instanceof LinkedInClientError) {
+    switch (error.code) {
+      case 'NOT_FOUND':
+        console.log('Profile not found in database');
+        break;
+      case 'AUTH_ERROR':
+        console.log('Invalid API key');
+        break;
+      case 'INVALID_REQUEST':
+        console.log('Missing required parameters');
+        break;
+      default:
+        console.log('API error:', error.message);
+    }
+  }
+}
+```
+
+### TypeScript Types
+
+```typescript
+import type { 
+  CosiallProfileEmailsResponse, 
+  ProfileEmailsLookupOptions 
+} from 'linkedin-secret-sauce';
+
+// Response type
+interface CosiallProfileEmailsResponse {
+  profileId: number;
+  objectUrn: string;
+  linkedInUrl: string;
+  emails: string[];
+}
+
+// Options type
+interface ProfileEmailsLookupOptions {
+  objectUrn?: string;
+  linkedInUrl?: string;
+  vanity?: string;
+}
+```
+
+## Notes
+
+- **Empty Emails Array**: A 200 OK response with an empty `emails` array means the profile exists but no emails are stored for it.
+
+- **URL Normalization**: The endpoint handles various URL formats:
+  - With or without trailing slash: `linkedin.com/in/john-doe` or `linkedin.com/in/john-doe/`
+  - With or without `https://` prefix
+
+- **Data Freshness**: Emails are retrieved from Cosiall's database and reflect the data collected during profile enrichment.
+
+- **Deduplication**: Email addresses are automatically deduplicated in the response.
+
+## Related Endpoints
+
+| Endpoint | Description |
+|----------|-------------|
+| `GET /api/flexiq/linkedin-cookies/all` | Retrieve Sales Navigator session cookies |
+
+## Playground Testing
+
+The LinkedIn Secret Sauce Playground includes a dedicated "Cosiall" tab for testing the Profile Emails API. Start the playground with:
+
+```bash
+pnpm dev:playground
+```
+
+Then navigate to the "Cosiall" tab to interactively test lookups by vanity, URL, or ObjectURN.