linkedin-secret-sauce 0.12.2 → 0.12.3

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.